Skip to main content

Restrict a Secret Key to specific IP addresses

Warning

IP allowlists for Secret Keys require a Business or Enterprise plan for production use, but you can try them for free in development mode. See the pricing page for more information.

If you downgrade to a plan without IP allowlists, Clerk removes them from your production Secret Keys when the downgrade takes effect. Those keys can then be used from any IP address. Allowlists on development and staging instances aren't affected.

An IP allowlist limits where a can be used from. Clerk's Backend API rejects requests made with the key from IP addresses outside its allowlist, except for the requests listed below. If the key leaks, an attacker can't use it from their own machine to read or change your data.

Each Secret Key has its own allowlist. A key without an allowlist can be used from any IP address.

Before you start

Find the public IP addresses your server uses to make outbound requests (its egress IPs), for every place the key is used:

  • Your backend servers: Use each server's public IP address. If requests go through a network address translation (NAT) gateway or an outbound proxy, use its public IP address instead. Clerk doesn't see private addresses such as 10.0.0.5.
  • Your hosting provider: Many serverless and edge platforms send requests from shared, changing IP addresses. Check whether your provider offers static egress IPs (e.g., Vercel's Static IPs, a NAT gateway on AWS or Google Cloud), and allowlist those.
  • Cloudflare Workers: Requests from Workers reach Clerk from 2a06:98c0:3600::103, an address shared by every Worker. Don't add it to an allowlist, since any Worker could then use your key.
  • CI/CD pipelines, build steps, and scripts: Anything else that uses the key, such as a build that prerenders pages with clerkClient, a migration script, or an admin CLI.
  • IPv6: Clerk's Backend API accepts IPv6. A server with IPv6 connectivity often uses it to reach Clerk, and may switch between IPv4 and IPv6 from one request to the next. Allowlist both its public IPv4 and IPv6 addresses, or turn off IPv6 on that server. IPv6 traffic often bypasses a NAT gateway (e.g., on AWS, it uses each instance's own IPv6 address). To cover servers you add or replace, you can allowlist their IPv6 subnet, as long as no one else uses addresses in it.

Tip

Create a separate Secret Key for each place a key is used (e.g., api-production, github-actions) and give each its own allowlist. A list for a server with fixed IPs can then be narrow, while a key used from somewhere without fixed IPs can stay unrestricted. See Rotate your Clerk API keys for how to add keys.

Add an IP allowlist to a Secret Key

  1. At the top left of the Clerk Dashboard, select the application and environment (e.g., Development or Production) you want to configure.
  2. In the sidenav, navigate to the API keys page.
  3. Under Secret keys, find the key and select the lock icon (Add IP allowlist).
  4. In the IP address or range field, enter an IP address or CIDR range and select Add. Repeat for each entry.
  5. Select Save.

Changes take about a minute to apply. After that, keys with an allowlist show the number of entries next to their name.

To remove the restriction, open the same dialog, remove every entry, and select Save.

Supported entries

  • IPv4 addresses (e.g., 203.0.113.10) and IPv6 addresses (e.g., 2001:db8::10).
  • IPv4 and IPv6 CIDR ranges (e.g., 203.0.113.0/24, 2001:db8::/48). A range must be written as its network address. For example, enter 203.0.113.0/24, not 203.0.113.10/24.
  • A /32 or /128 entry matches one address. For example, 2001:db8:1:2::/128 matches only 2001:db8:1:2::. To allow the network, enter 2001:db8:1:2::/64.
  • Up to 50 entries per key.

Note

Private, loopback, and link-local addresses (e.g., 10.0.0.0/8, 192.168.0.0/16, 127.0.0.1, ::1) aren't accepted, since requests to Clerk never come from them.

Which requests the allowlist restricts

The allowlist applies to Backend API requests that use the key, whether they come from a Clerk SDK or from your own HTTP client.

The allowlist doesn't restrict the following Backend API requests, from any caller. Clerk's SDKs make them while authenticating requests, and exempting them lets middleware run on hosts without fixed IP addresses, such as edge runtimes:

Warning

The allowlist doesn't apply when the Secret Key is sent to the Frontend API through a proxy.

When a request is rejected

A request from an IP address that isn't on the key's allowlist fails with a 403 status code and the secret_key_ip_not_allowed error code. When available, the error includes the IP address Clerk saw, so you can compare it with your list:

{
  "errors": [
    {
      "code": "secret_key_ip_not_allowed",
      "message": "IP address not allowed",
      "long_message": "This secret key can only be used from the IP addresses in its allowlist. The request came from 198.51.100.7.",
      "meta": { "ip": "198.51.100.7" }
    }
  ]
}

If you see this error from an address you expect to be allowed, check whether the request went out over IPv6, through a different region or NAT gateway, or from a build step or local machine.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub