> ## Documentation Index
> Fetch the complete documentation index at: https://www.unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Unkey is two separate products. Compute builds, deploys, and runs apps behind a gateway. API Management issues API keys, enforces rate limits, manages identities and permissions, and reports usage. Say which product a page belongs to; a reader can use either without the other.
> Every Unkey API endpoint is an HTTP POST to https://api.unkey.com/v2/{service}.{procedure} with a root key in the Authorization: Bearer header. Root keys are workspace scoped.
> Error codes have the form err:{system}:{category}:{specific} and each has a page at /errors/{system}/{category}/{specific}.
> The word environment means production or preview in Compute. Rate limiting has four meanings on this site; the glossary lists them.

# IP allowlists

> Limit the source addresses that can authenticate with a root key.

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](https://www.unkey.com/docs/compute/gateway/firewall.md) 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](mailto: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.

![Edit key panel with two entries in the IP allowlist field](https://mintcdn.com/unkeyed/XTd-RM-5eWFQf8WW/platform/root-keys/root-key-ip-allowlist-light.png?fit=max\&auto=format\&n=XTd-RM-5eWFQf8WW\&q=85\&s=1de6c42641f321f4f69afca3bc5f084c)

## 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.

```bash wrap theme={"system"}
curl --fail-with-body https://api.unkey.com/v2/rootKeys.updateKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "keyId": "key_xxx",
    "ipAllowlist": ["203.0.113.10", "198.51.100.0/24", "2001:db8::/32"]
  }'
```

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](#delegation-cannot-widen-network-access). 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.