Documentation

IP allowlist

An IP allowlist is an optional, per-key network control. When a key has at least one entry, the API accepts the key only from a source IP that matches an entry. A key without an allowlist works from any IP.

The allowlist supplements HMAC authentication. It never replaces the signature and it does not grant scopes.

Rules

Rule	Value
Entry types	Exact IPv4 or IPv6 address, or CIDR range
Maximum entries	50 per key
Address families	Each entry must match the family of the source IP
Hostnames	Not supported
Wildcards	Not supported
Empty allowlist	Any source IP

Examples of accepted entries:

Code
203.0.113.10
203.0.113.0/24
2001:db8:1234::/48
2001:db8:1234::7

Examples that are rejected or never match:

Code
api.example.com        # hostnames are not resolved
203.0.113.*            # wildcards are not supported
::ffff:203.0.113.10    # map explicitly to the IPv4 family or use the IPv4 form

0.0.0.0/0 and ::/0 are accepted by the parser but defeat the control. Do not use them on live keys.

Configure an allowlist

Dashboard

The partner owner can set an allowlist when creating an agent key, or update the key from the dashboard. Use commas or newlines between entries.

API

POST /v1/agents/{agentId}/keys accepts an optional ipAllowlist array. The trailing 50 entries are kept if you send more.

Code
{
  "name": "production agent",
  "ipAllowlist": ["203.0.113.0/24", "2001:db8:1234::/48"]
}

The response contains the API ID and the secret once. It never returns the secret again.

How the source IP is determined

The API derives the client IP in this order:

Read the peer address of the connection.
If the peer is a configured trusted proxy, prefer CF-Connecting-IP.
Otherwise use the first valid address in X-Forwarded-For.
If no trusted proxy header is valid, use the peer address.

Clients cannot choose their allowlisted address by setting X-Forwarded-For when they are not coming through a trusted proxy. If your integration runs behind your own egress proxy, use the proxy's public egress addresses in the allowlist.

Failure behaviour

A mismatch returns:

Code
HTTP/1.1 403 Forbidden
Content-Type: application/json
X-Error-Code: ip_not_allowed

{"error":{"code":"ip_not_allowed","message":"This IP address is not allowed for this key."}}

403 ip_not_allowed is not a signature failure. Fix the network path or the allowlist. Do not retry from the same address with a different nonce.

Operational guidance

Use one key per environment and per workload. An allowlist on a shared key couples unrelated systems to the same egress addresses.
Use the narrowest range that covers the egress pool. Prefer /32 for a single IPv4 host and /128 for a single IPv6 host.
Include IPv6 if your provider uses it. A dual-stack host may reach the API over IPv6 even when you tested over IPv4.
Update the allowlist before changing an egress pool. A key that suddenly fails is often a network change, not an authentication change.
Monitor 403 ip_not_allowed responses. A sustained rise can mean a misconfigured proxy or a credential used from an unexpected network.
Treat the allowlist as defence in depth. It is not a substitute for protecting the secret.

Troubleshooting

Check	Action
What address does the API see?	Log the public egress address from the calling host, not the internal container address.
Is the key allowlist empty?	An empty list means any IP. Check the key you actually used.
Is the address IPv6?	Add the IPv6 range as well as the IPv4 range.
Is the CIDR aligned?	`203.0.113.10/24` is not a valid network; use `203.0.113.0/24`.
Is the key expired?	Rotate the key, then re-check the allowlist on the new key.

For scope failures after a valid signature, see Authentication. For request errors, see Errors.

Authentication Limits and quotas