Authentication

Authenticate every Tatum API and RPC Gateway request with an API key from the Tatum Dashboard.

Log in to see your API keys
API KeyLabelLast Used

Send your Tatum API key with every request. Keys are created in the Tatum Dashboard and are bound to your account and plan, which sets your rate limit and monthly credits. See Plans & Limits.

🔑

Log in to use your own keys.

Log in to docs.tatum.io with your Tatum Dashboard account. Your API keys are listed on this page and prefilled in every Try It request in the API Reference. No account yet?

Create one for free

API keys

  • Every account starts with two keys: one for mainnet and one for testnet. Use the key that matches the network you call. See Mainnet and testnet.
  • Paid plans can create more keys on the API Keys page.
  • One key works across all Tatum APIs: Blockchain Data, Notifications, RPC Gateway (https://{chain}-{network}.gateway.tatum.io), and the REST API (https://api.tatum.io/v3, https://api.tatum.io/v4).
  • Keys are secrets. Keep them server-side, and restrict keys used in browsers or apps to your IP addresses and origins. See API key access restrictions.

Manage keys

Manage keys on the API Keys page in the Tatum Dashboard. Only the organization owner can regenerate or expire a key.

ActionResult
RegenerateReplaces the key string. The old key stops working immediately. Notification subscriptions, the HMAC webhook secret, and Virtual Accounts are kept.
ExpireStops the key permanently and deletes its Virtual Accounts, Notification subscriptions, and HMAC webhook secret. Can't be undone.
RestrictAccepts requests only from listed IP addresses or origins. See API key access restrictions.

If a key is exposed, follow Handling Exposed API Keys. To rotate a key used with Notifications or Virtual Accounts, regenerate it; don't expire it.

Authentication methods

MethodFormatUse
x-api-key headerx-api-key: {YOUR_API_KEY}Recommended for all requests.
Authorization header, Bearerauthorization: bearer {YOUR_API_KEY}Clients that only support Bearer tokens.
Authorization header, Basichttps://x-api-key:{YOUR_API_KEY}@{HOST}Clients that only support Basic auth.
Query parameter?xApiKey={YOUR_API_KEY}Legacy, selected endpoints only. Avoid.
Path segmenthttps://{HOST}/{YOUR_API_KEY}Legacy, selected endpoints only. Avoid.

Replace {YOUR_API_KEY} with your API key and {HOST} with the API host, for example api.tatum.io or ethereum-mainnet.gateway.tatum.io.

x-api-key header

curl 'https://api.tatum.io/v4/data/blockchains/block/current?chain=ethereum-mainnet' \
  --header 'x-api-key: {YOUR_API_KEY}'
curl 'https://ethereum-mainnet.gateway.tatum.io' \
  --header 'content-type: application/json' \
  --header 'x-api-key: {YOUR_API_KEY}' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
import { TatumSDK, Ethereum, Network } from '@tatumio/tatum'

const tatum = await TatumSDK.init<Ethereum>({
  network: Network.ETHEREUM,
  apiKey: { v4: '{YOUR_API_KEY}' },
})

Authorization header

curl 'https://ethereum-mainnet.gateway.tatum.io' \
  --header 'content-type: application/json' \
  --header 'authorization: bearer {YOUR_API_KEY}' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
curl 'https://x-api-key:{YOUR_API_KEY}@ethereum-mainnet.gateway.tatum.io' \
  --header 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

API key in the URL

🚧

Avoid keys in URLs

Browsers, proxies, servers, and analytics tools log URLs, and the Referer header can leak them to third parties. Use the x-api-key header instead.

curl 'https://ethereum-mainnet.gateway.tatum.io?xApiKey={YOUR_API_KEY}' \
  --header 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
curl 'https://ethereum-mainnet.gateway.tatum.io/{YOUR_API_KEY}' \
  --header 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Priority

Send the key with one method only. If a request carries more than one, Tatum uses the first match in this order:

  1. x-api-key header
  2. Authorization header
  3. ?xApiKey query parameter
  4. Key in the path

Errors

StatusCauseFix
401 UnauthorizedNo API key, or the key is invalid. errorCode is subscription.invalid (REST API) or ip-address-key.unauthorized.Send a valid key in the x-api-key header.
403 ForbiddenFree plan credits are used up.Upgrade your plan.
403 ForbiddenThe request's IP address or origin isn't on the key's allowlist. The x-ttm-error-reason header is ip_not_allowed, origin_not_allowed, or origin_missing.Update the key's allowlists in the Tatum Dashboard.
429 Too Many RequestsThe account exceeded its requests-per-second limit.Slow down, or upgrade your plan. See HTTP 429.

Many REST API error responses include a dashboardLog link with a request ID. Include it when you report an error to support.

Example responses: Authentication Errors. Managing, rotating, and protecting keys: Authentication & Security.

Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Did this page help you?