Authentication & KeysIP Allowlists

IP Allowlists

Pin an API key or OAuth client to a set of source IP ranges (CIDRs). Requests from anywhere else get a 403, even with the correct key.

What it does

An IP allowlist binds a credential to network origin: even a valid key presented from outside the configured CIDR ranges is rejected with forbidden-ip 403. If a key leaks, the thief also needs to originate traffic from inside your network ranges.

  • Allowlists are per credential (per API key or OAuth client), not per account — you can pin your production key to your egress IPs while leaving a developer's test key unrestricted.
  • The IP check runs before the scope check; a disallowed IP wins even when the scope is also missing.
  • The 403 body names the problem type only. It never echoes the caller's IP or your configured ranges — nothing for a prober to learn.

Setting it up

Workspace admins and owners manage allowlists themselves in the portal: open API keys, choose Allowlist & limits on the key, and add one block at a time (for example 203.0.113.0/24 or 198.51.100.7/32). Changes apply to the key's next request.

  • Up to 20 blocks per key. Blocks are stored as networks, so 203.0.113.7/24 is saved as 203.0.113.0/24.
  • Very wide blocks are refused: IPv4 /8 or wider and IPv6 /32 or wider (this includes 0.0.0.0/0 and ::/0). Use the narrowest ranges your egress actually uses.
  • Removing the last block makes the key usable from any address again; the portal asks you to confirm.
  • Rotating a key copies its allowlist to the new key.
  • Every change is recorded in your workspace's audit trail.

The same operations are available on the portal API (GET/POST /v1/portal/keys/{id}/cidrs, DELETE /v1/portal/keys/{id}/cidrs/{cidr} with the block URL-encoded). OAuth client allowlists are still configured by our team — contact support with the client ID (never the secret) and the ranges.

We recommend allowlisting any long-lived tk_live_ key whose egress IPs are stable (most cloud NAT gateways and corporate proxies qualify).

Troubleshooting

Getting forbidden-ip unexpectedly usually means your egress IP changed — a NAT gateway replacement, a new deployment region, or a proxy change. Compare your current egress IP (curl -s https://ifconfig.me from the affected host) with the ranges on the key, and update them under Allowlist & limits.

Was this page helpful?