Skip to main content
An IP allowlist limits the source addresses that can authenticate with a root key. It accepts IPv4 addresses, IPv6 addresses, and CIDR ranges. It restricts your service’s calls to Unkey, not the end users whose API keys your service verifies. For applications hosted on Compute, use a firewall policy to restrict incoming client addresses. Allowlist changes can take up to 30 seconds to take effect. IP allowlists are a paid add-on. Contact support@unkey.com to add them to your workspace. Until the add-on is enabled, the dashboard shows a disabled field with a Contact support link. If the add-on is later disabled, root keys with saved allowlists still reject requests from addresses outside those lists. You cannot edit or clear the lists through the dashboard or API while the add-on is disabled. A root key with a saved allowlist also can’t create root keys while the add-on is disabled, because new keys inherit its allowlist.

​
Configure the allowlist in the dashboard

  1. Open Root Keys and choose Edit root key from the key’s row menu.
  2. In IP allowlist, enter one IP address or CIDR range per line.
  3. Include every outbound address your service uses to call Unkey, including NAT or proxy addresses.
  4. Click Save.
Leave the field empty for unrestricted IP access. Other authentication and permission checks still apply.

​
Configure the allowlist through the API

Send ipAllowlist to rootKeys.updateKey with the complete replacement list. The caller needs write on the target root key. The array accepts up to 100 entries. Use addresses and CIDR ranges, not hostnames or addresses with ports.
Replace key_xxx with the target key’s ID and the example networks with your service’s outbound addresses. Omit ipAllowlist to leave it unchanged. Send "ipAllowlist": [] to remove the IP restriction, subject to workspace enablement and the delegation rules. An empty array is valid; an empty string inside the array is not. You can also set ipAllowlist in rootKeys.createKey. If you omit it, the new key inherits the caller’s allowlist. An unrestricted caller creates an unrestricted key. A restricted caller can provide a narrower list, but cannot provide a broader list or []. rootKeys.listKeys returns each key’s allowlist. Rotation preserves the existing list.

​
Delegation cannot widen network access

A restricted root key can create or update another key only within its own allowed networks. An update can expand the target’s existing list, but cannot allow addresses outside the caller’s networks. A restricted caller cannot clear the list or expand its own allowed networks. A restricted caller also can’t update or rotate a key with a broader allowlist or no allowlist, even if the request doesn’t change the allowlist. For example, a caller restricted to 198.51.100.0/24 can expand a target from 198.51.100.10 to 198.51.100.0/24. It cannot permit 203.0.113.10 or make the target unrestricted. Removing all IP restrictions requires an unrestricted caller or a dashboard admin, with the paid add-on enabled.

​
Verify the restriction

For example, restrict a root key to 203.0.113.10 and use it in the Authorization header of a keys.verifyKey request. A request from 203.0.113.10 passes root-key authentication and proceeds to verify the end-user key in the request body. The same request from 198.51.100.20 returns HTTP 401 before that key is verified, even if the end-user key is valid. The response matches a missing root key and does not reveal that the restricted key exists. It contains an error object, not a verification result in data.code.
Last modified on November 12, 2026