Skip to content
Knowledge base

Restrict an API key to an IP allowlist

Make a key usable only from your CI runner, server, or office egress addresses. Requests from anywhere else get a 403.

1. Find the caller's real public address

Run a lookup from the host that will make the requests, for example curl https://api.ipify.org. Use that address (or the range your provider documents for its egress), not the address of the laptop you are reading this on. A NAT gateway, VPN, or cloud egress can differ from what ifconfig shows.

2. Set the list on the key

In your account's API & MCP access section, fill in IP allowlist when generating a key, or open an existing key's menu and choose Edit IP allowlist. Entries are IPv4 or IPv6, as a bare address (203.0.113.9) or a CIDR range (198.51.100.0/24, 2001:db8::/32), one per line or comma-separated, up to 20 per key. A catch-all such as 0.0.0.0/0 is refused: leave the list blank instead if the key should work from anywhere.

3. Know what a refusal looks like

A request from outside the list answers 403 with code RU-1007 on both the REST API and the MCP server, checked before any handler runs. The response never reveals the allowed addresses. The address checked is the one our edge proxy sees; an X-Forwarded-For header sent by the client is ignored, so it cannot be used to claim an allowed address.

4. Change or clear it any time

Edits apply on the very next request, with no cache in between. Clearing the list makes the key valid from anywhere again. Every change is written to your account audit log as 'API key IP allowlist updated' with the before and after lists. For a fleet with many egress addresses, prefer a separate restricted key per integration over one long list.

Go deeper

The full reference lives in the docs: API documentation, IP allowlists. Error codes named above are each explained in the error-code reference.