Shared rate limits across keys

A rate limit on a key counts that key alone. If a user has three keys at 100 requests per minute each, they can make 300. Put the limit on the user’s identity instead, and all their keys share the same 100. Here’s how to set it up.

Create a root key with the permissions listed on this page under Root Keys in the dashboard sidebar. CLI commands can instead use a session from unkey login with the required permissions. See Permission reference for every permission.

To create the identity, your root key needs unkey:v1:<workspaceId>:projects/<projectId>/identities/*#write for the workspace’s default project. To update an existing identity, it needs unkey:v1:{workspaceId}:projects/{projectId}/identities/{identityId}#write. It also needs unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write for creating keys, and unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#verify for the keyspace. Use the keyspace’s project ID for creating keys.

Create the identity with a limit

autoApply: true makes the limit count on every verification without the caller naming it.

curl -X POST https://api.unkey.com/v2/identities.createIdentity \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_123",
    "ratelimits": [
      { "name": "requests", "limit": 100, "duration": 60000, "autoApply": true }
    ]
  }'

const { data } = await unkey.identities.createIdentity({
  externalId: "user_123",
  ratelimits: [
    { name: "requests", limit: 100, duration: 60_000, autoApply: true },
  ],
});
console.log(data.identityId);

If the identity already exists, for example because a key was created with this externalId earlier, the call returns HTTP 409 err:unkey:data:identity_already_exists. Use identities.updateIdentity with the same ratelimits array instead.

Create keys that belong to it

Any key created with the same externalId is linked to the identity.

curl -X POST https://api.unkey.com/v2/keys.createKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "apiId": "api_...", "externalId": "user_123", "name": "Production" }'

await unkey.keys.createKey({ apiId: "api_...", externalId: "user_123", name: "Production" });
await unkey.keys.createKey({ apiId: "api_...", externalId: "user_123", name: "Staging" });

Verify any of the keys

The identity limit is auto-applied, so a plain verification enforces it. Requests through the production key and the staging key both draw down the same 100 per minute.

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "sk_..." }'

const { data } = await unkey.keys.verifyKey({ key: incomingKey });

if (!data.valid && data.code === "RATE_LIMITED") {
  // the user exceeded 100 requests per minute across all their keys
}
console.log(data.identity?.externalId); // "user_123"

data.ratelimits shows the limits that were checked, with remaining and reset.

Several limits on one identity

Add more than one limit when different operations need different budgets. A limit with autoApply: false is only checked when a verification names it, so an expensive endpoint can have its own budget.

curl -X POST https://api.unkey.com/v2/identities.updateIdentity \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity": "user_123",
    "ratelimits": [
      { "name": "requests", "limit": 500, "duration": 3600000, "autoApply": true },
      { "name": "tokens", "limit": 20000, "duration": 86400000, "autoApply": false }
    ]
  }'

Then spend 150 tokens on one call:

curl -X POST https://api.unkey.com/v2/keys.verifyKey \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "sk_...", "ratelimits": [ { "name": "tokens", "cost": 150 } ] }'

Both requests (auto-applied) and tokens are checked together. If either is exceeded, the verification returns RATE_LIMITED and neither is consumed.

Exceptions for one key

If a key has a limit with the same name as one on its identity, the key’s limit wins for that key. Use this to give one integration a higher limit than the user’s other keys. Details are in Key and identity rate limits.

Get started

Framework guides

Keyspaces

Keys

Rate limiting

Identities

Authorization

Analytics

Developer portal

Security

Cookbook

Shared rate limits across keys

Create the identity with a limit

Create keys that belong to it

Verify any of the keys

Several limits on one identity

Exceptions for one key

Create the identity with a limit

Create keys that belong to it

Verify any of the keys

​Several limits on one identity

​Exceptions for one key

Several limits on one identity

Exceptions for one key