🔑 Authentication & Security

Access Tatum services by authenticating with your API key using one of the methods below.

API keys are bound to a Tatum account and a pricing plan, defining the number of requests you can make per second, as well as the total number of requests available each month.

How to Authenticate Your Requests?

1. Create or sign in to your account at Tatum Dashboard.
2. Each free account includes two API keys – one for Mainnet and one for Testnet. Learn more →
3. Use your API key to authenticate all requests – and you're ready to build! 🎉

Authentication methods

X-API-Key in header (Recommended)

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

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

API Key in the SDK

import { TatumSDK, Ethereum, Network } from '@tatumio/tatum'

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

Authorization Header (Bearer)

This format mimics HTTP Bearer Authentication by passing the API key in the 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://api.tatum.io/v3/bitcoin/wallet' \
--header 'authorization: bearer {YOUR_API_KEY}'

Authorization Header (Basic)

We also support HTTP Basic Authentication. For your convenience, most HTTP clients handle this for you by accepting the below format.

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
}'

curl 'https://x-api-key:{YOUR_API_KEY}@api.tatum.io/v3/bitcoin/wallet'

API key as a part of the URL

We support passing the API key as a query parameter (?xApiKey=YOUR_API_KEY) or in the path. These methods are available for specific backward-compatible endpoints and should only be used with caution in trusted environments.

⚠️

Not Recommended

Including API keys in URLs poses significant security risks and should be avoided, especially in production environments or client-side applications (e.g., web frontends, mobile apps).

• URLs can be logged by browsers, proxies, servers, and analytics tools.
• Referrer headers may leak the full URL to third parties.
• It's easier to accidentally share or expose URLs containing sensitive data.

Instead, use the x-api-key header which is more secure and aligned with best practices.

?xApiKeyquery parameter

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
}'

{xApiKey} in path (if supported)

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
}'

Authentication priority evaluation

❗️

Do not combine multiple authentication methods

This can lead to unexpected behavior.

Best Practices for Security

• Keeping API Keys Secure: Understand how to disable or regenerate API keys to maintain the integrity of your digital operations.
• Managing Mnemonics and Private Keys: Discover strategies for securely managing your mnemonics and private keys to prevent loss, as Tatum does not store this sensitive information.
• Malicious Addresses: Learn how to identify and avoid blockchain addresses associated with scams, helping you stay ahead of fraudulent activities.
• Compromised Assets: Find out what steps to take if your mnemonics or private keys are compromised, including securing remaining assets and contacting law enforcement.