API key access restrictions

Access restrictions limit where an API key works. Each API key can carry an allowlist of IP addresses and an allowlist of origins (websites). Tatum rejects requests that don't match, so a leaked key restricted by IP address doesn't work outside your own servers.

Restrictions protect the key, not an endpoint. They apply to every request made with that key, however you send it: in the x-api-key header, as a Bearer token, or in the URL. Requests sent without an API key aren't affected; the RPC Gateway still serves them on its anonymous tier. Restrictions are available on all plans and for every API key, shared or dedicated, mainnet or testnet.

You manage restrictions per key on the API Keys page of the Tatum Dashboard. To create, regenerate or expire keys, see Managing API Keys.

How matching works

Requests that don't match get 403 Forbidden. Tatum reads the client IP address from its own network edge, so headers such as X-Forwarded-For can't be used to fake it.

Restrict an API key

1. Log in to the Tatum Dashboard.
2. Go to the API Keys page.
3. In the Allowlist column, click the key's pill. An unrestricted key shows Any IP or origin. You can also open the key's ⋮ menu and click Access restrictions.
4. In Allowed IP addresses or Allowed origins, enter one or more entries and click Add. You can paste many at once, separated by commas, semicolons, spaces, tabs or new lines, or as a JSON array. Everything after a # on a line is treated as a comment and ignored.
5. Optionally, give each entry a Label, such as the server or app it belongs to.
6. Click Save changes. When a save could block traffic, for example the first time you restrict a key or when you add a second list, the Dashboard asks you to confirm first.

Every change, including removing entries, can take up to a minute to apply.

Add my current IP adds the public IP address you're browsing from. Entries that aren't valid stay in the input box with an error, and the rest are added.

Supported formats

• Origins need the https:// or http:// scheme and contain only the host and an optional port, with no path. They aren't case-sensitive, and a trailing slash or default port is dropped.
• Wildcards are allowed only as a leading *. on a domain name, and match only the same scheme and port. To allow example.com itself, add it as a separate entry. https://*.com and wildcards on IP addresses aren't allowed.
• IP addresses are saved in a standard form. A range is saved as its network address, so 203.0.113.7/24 becomes 203.0.113.0/24. IPv6 addresses are saved in lowercase, shortened form, so 2001:DB8:0:0::7 becomes 2001:db8::7. Duplicates are detected after this.
• Use public IP addresses. Add the public outgoing IP of your servers. Private ranges such as 10.0.0.0/8 only match requests from inside a private network.
• Limits: up to 1,000 entries per key, IP addresses and origins combined. Each entry can be up to 300 characters, and each label up to 50.

Find your server's outgoing IP address

Tatum sees the public IP address your requests leave your network from, which often isn't the server's own address.

• Check it from the server itself: run curl -4 https://icanhazip.com for IPv4 and curl -6 https://icanhazip.com for IPv6, or use any other IP-echo service from the machine that calls Tatum. Add both addresses if both commands return one.
• Servers behind NAT, a proxy or a load balancer call out from the gateway's address. In the cloud, that's typically the static IP of your NAT gateway, such as an AWS NAT Gateway or GCP Cloud NAT.
• Kubernetes: pods usually leave through the node's IP address or the cluster's NAT. Use a static egress IP so the address doesn't change when nodes are replaced.
• IPv4 and IPv6: Tatum is reachable over both. A server with both kinds of address can use either, so add both its IPv4 and IPv6 addresses.
• Laptops and phones usually reach the internet from temporary IPv6 addresses that change about once a day. Allow your network's /64 prefix rather than a single address. Your provider may still change that prefix, and everyone on the same network shares it. For servers, allow the server's exact address.

Blocked requests

Tatum rejects a request that doesn't match the key's allowlists with HTTP 403 Forbidden. The request isn't processed and doesn't use credits.

The response body says what to fix, and the x-ttm-error-reason header gives a machine-readable reason. Browsers can read the header from JavaScript.

{
  "statusCode": 403,
  "message": "Requests from IP address 203.0.113.7 are not allowed for this API key. Update the allowed IP addresses in the Tatum Dashboard."
}

When both lists are set and a request fails both, the IP address is reported. Browser preflight (OPTIONS) requests aren't blocked; the actual request gets the 403.

Blocked requests appear in Access Logs with status 403.

Troubleshooting a 403

• ip_not_allowed: add the IP address from the message, or its range, to the key's IP list. Check the server's outgoing address as described in Find your server's outgoing IP address.
• origin_missing: the key has an origin list, but the request came from a server or tool that sends no Origin header. Use a separate key restricted by IP address for server-side calls.
• origin_not_allowed: add the origin from the message to the key's origin list. The scheme and port must match.
• Just changed the lists? Wait up to a minute for the change to apply.
• WebSocket connections and gRPC streams are checked when they open. One opened before you restricted a key keeps working until it reconnects.

Use a restricted key in the Dashboard

Some Dashboard pages call Tatum from your browser with the selected API key, for example Access Logs, Error Logs, Notifications, Data Insights and AI Builder. These requests come from your current IP address and the Dashboard's origin, https://dashboard.tatum.io. If the key's lists don't include them, those pages can't load data with that key.

The Dashboard detects this:

• When you restrict a key, the confirmation dialog shows whether the new lists block the Dashboard and offers Also allow my current IP and Also allow the Dashboard.
• When a page can't load because of a key's restrictions, the Dashboard shows This API key blocks the Dashboard. Click Allow the Dashboard to open the key's access restrictions with the missing IP address or origin already added, then click Save changes. You can also switch to a key that the Dashboard can use.

Origin vs. IP restrictions

• Server-side keys: restrict by IP address. This is the stronger control.
• Browser keys: restrict by origin, so the key only works on your websites. Treat the key as public anyway.

Best practices

• An IP allowlist is one layer of protection. Combine it with the practices below rather than relying on it alone.
• Use a separate key per app and environment, so you can restrict, rotate or expire one without affecting the others.
• Keep keys out of code and repositories. Store server keys in a secret manager or environment variables.
• Rotate keys regularly, and right away if a key may have leaked. See Managing API Keys.
• Watch Access Logs for 403 responses, which show requests from places you didn't allow.

Remove restrictions

1. Open the key's access restrictions from the Allowlist column on the API Keys page.
2. Remove the entries you no longer need. With both lists empty, the key accepts requests from anywhere again.
3. Click Save changes.

Audit changes

Every change to a key's allowlist and every key rename is recorded in your account's activity history. To review it, go to Account in the Dashboard and scroll to History.