Authenticate every Tatum API and RPC Gateway request with an API key from the Tatum Dashboard.
| API Key | Label | Last 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?
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.
| Action | Result |
|---|---|
| Regenerate | Replaces the key string. The old key stops working immediately. Notification subscriptions, the HMAC webhook secret, and Virtual Accounts are kept. |
| Expire | Stops the key permanently and deletes its Virtual Accounts, Notification subscriptions, and HMAC webhook secret. Can't be undone. |
| Restrict | Accepts 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
| Method | Format | Use |
|---|---|---|
x-api-key header | x-api-key: {YOUR_API_KEY} | Recommended for all requests. |
Authorization header, Bearer | authorization: bearer {YOUR_API_KEY} | Clients that only support Bearer tokens. |
Authorization header, Basic | https://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 segment | https://{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
x-api-key headercurl '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
Authorization headercurl '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 URLsBrowsers, proxies, servers, and analytics tools log URLs, and the
Refererheader can leak them to third parties. Use thex-api-keyheader 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:
x-api-keyheaderAuthorizationheader?xApiKeyquery parameter- Key in the path
Errors
| Status | Cause | Fix |
|---|---|---|
401 Unauthorized | No 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 Forbidden | Free plan credits are used up. | Upgrade your plan. |
403 Forbidden | The 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 Requests | The 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.