API key IP allowlists

An API key IP allowlist restricts where an Ed25519 API key can be used. Polyester accepts a correctly signed request only when its authoritative client address belongs to at least one CIDR configured on the key.

Use an IP allowlist as defense in depth. It limits the usefulness of a stolen private key, but it does not replace secure key storage, request signing, API-key policies, or endpoint authorization.

Allowlist behavior

• An omitted or empty allowlist means the key has no IP restriction.
• A non-empty allowlist permits a request when any configured CIDR contains the client address.
• Matching is family-aware after IPv4-mapped IPv6 addresses are normalized to IPv4. Ordinary IPv4 addresses do not match IPv6 CIDRs, and ordinary IPv6 addresses do not match IPv4 CIDRs.
• Each entry must include a prefix length. Use /32 for one IPv4 address and /128 for one IPv6 address.
• A key supports up to 32 unique CIDR entries.
• Send canonical network prefixes. Entries that resolve to the same normalized network are rejected as duplicates.
• The restriction applies to every endpoint and transport that accepts the API key.
• A request outside the allowlist fails authentication before the domain operation runs.

Polyester determines the client address from the network connection and trusted network path. Forwarding headers supplied by an untrusted public client cannot select or override the address used for this check.

Choose the correct source addresses

Allow the public egress addresses that Polyester sees for your integration. These are commonly the static NAT gateway or proxy addresses used by your production workload.

Before enabling a restriction:

1. Confirm the public IPv4 and IPv6 egress addresses for every production region.
2. Include redundant egress paths used during failover.
3. Avoid broad network ranges when a host prefix is sufficient.
4. Do not use workstation, mobile, or other frequently changing addresses for unattended production integrations.

Configure an allowlist when creating a key

Set ipWhitelist when calling POST /v1/auth/api-keys. The public key is Base64-encoded because publicKeyEd25519 is a protobuf bytes field in JSON.

{
	"label": "production-trading",
	"publicKeyEd25519": "<base64-ed25519-public-key>",
	"ipWhitelist": ["203.0.113.10/32", "2001:db8:1234::/48"]
}

The key can authenticate from 203.0.113.10 or any IPv6 address inside 2001:db8:1234::/48. Other source addresses are denied.

Replace or clear an existing allowlist

Update a key with PATCH /v1/auth/api-keys/{key_id}.

To replace the complete allowlist:

{
	"ipWhitelist": {
		"cidrs": ["198.51.100.24/32", "2001:db8:5678::/48"]
	}
}

To clear the allowlist and make the key unrestricted:

{
	"ipWhitelist": {
		"cidrs": []
	}
}

If ipWhitelist is omitted from an update, the current allowlist remains unchanged.

Handle denied requests

A request with a valid signature returns IP_NOT_ALLOWED with HTTP status 401 when its trusted client address is outside the configured ranges or cannot be safely determined.

Do not retry the same request unchanged. Retry only after one of these conditions is true:

• the request originates from an approved network
• an authorized account administrator has corrected the key's allowlist
• the key has been deliberately changed to unrestricted access

Changing forwarding headers does not correct the source address.

Production recommendations

• Generate and store the Ed25519 private key in a dedicated secret manager or signing service.
• Prefer one API key per workload and environment instead of sharing a key.
• Use narrow host prefixes for fixed egress addresses.
• Include IPv4 and IPv6 ranges only when the workload can use both address families.
• Attach the minimum API-key policy required by the integration.
• Disable or revoke a key immediately if its private key or approved network is compromised.
• Test failover from every approved egress path before relying on it during an incident.

See Ed25519 API keys for canonical request signing and API key replay protection for retry and idempotency guidance.

Related Topics