Per-user rate limits

Outcome: a user who holds several keys gets one shared , enforced by keys.verifyKey with no extra call, and users on a higher plan get a higher limit without a code change.

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.

Put the limit on the identity

A limit on a key applies to that key alone. A limit on an identity is shared by all the user’s keys. Create the identity with the limit, then create keys with the same externalId, and they’re linked automatically. autoApply: true checks the limit on every verification. For the first call, your root key needs unkey:v1:<workspaceId>:projects/<projectId>/identities/*#write for the workspace’s default project. For the second call, it needs unkey:v1:<workspace_id>:projects/<project_id>/keyspaces/<keyspace_id>/keys/*#write. Use the keyspace’s project ID for the second call.

create the identity

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",
    "meta": { "plan": "free" },
    "ratelimits": [
      { "name": "requests", "limit": 100, "duration": 60000, "autoApply": true }
    ]
  }'

create a key for that user

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" }'

Your handler doesn’t change. keys.verifyKey returns code: RATE_LIMITED when the shared limit is used up, and data.ratelimits has remaining and reset so you can send X-RateLimit-* headers.

verify and forward limit headers

const result = await unkey.keys.verifyKey({ key });
const rl = result.data.ratelimits?.find((r) => r.name === "requests");
const headers = rl
  ? {
      "X-RateLimit-Limit": String(rl.limit),
      "X-RateLimit-Remaining": String(rl.remaining),
      "X-RateLimit-Reset": String(rl.reset),
    }
  : {};
if (!result.data.valid) {
  return Response.json({ error: result.data.code }, { status: result.data.code === "RATE_LIMITED" ? 429 : 401, headers });
}

When a user upgrades, call identities.updateIdentity with a new ratelimits array (needs unkey:v1:{workspaceId}:projects/{projectId}/identities/{identityId}#write for the identity). It replaces the whole list, so send every limit the user should keep. All their keys pick up the change within about 10 seconds.

Alternative: the standalone ratelimit API

If you’re limiting something other than a key holder (a logged-in session, an IP address, a tenant), use ratelimit.limit. The namespace names what you’re limiting, the identifier is the user, and you send the limit with each request. The response is always HTTP 200, so read data.success.

curl -X POST https://api.unkey.com/v2/ratelimit.limit \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "namespace": "api.requests", "identifier": "user_123", "limit": 100, "duration": 60000 }'

const rl = await unkey.ratelimit.limit({
  namespace: "api.requests",
  identifier: userId,
  limit: 100,
  duration: 60_000,
});
if (!rl.data.success) {
  return Response.json({ error: "rate limited" }, { status: 429, headers: { "Retry-After": String(Math.ceil((rl.data.reset - Date.now()) / 1000)) } });
}

For plans, use overrides. An override gives one identifier a different limit from the one in the request. Set one when a user upgrades and delete it when they downgrade. data.overrideId in the response shows when an override applied. The root key needs ratelimit.*.limit to check limits and unkey:v1:<workspace_id>:projects/<project_id>/ratelimits/namespaces/<namespace_id>/overrides/*#write to create overrides.

give one user a higher limit

curl -X POST https://api.unkey.com/v2/ratelimit.setOverride \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "namespace": "api.requests", "identifier": "user_123", "limit": 1000, "duration": 60000 }'

Creating keys for the externalId and ratelimits fields.
Verifying keys for the ratelimits response entries.
Identities, standalone rate limiting, and overrides are documented under API Management.

Get started

Framework guides

Keyspaces

Keys

Rate limiting

Identities

Authorization

Analytics

Developer portal

Security

Cookbook

Per-user rate limits

Put the limit on the identity

Alternative: the standalone ratelimit API

Put the limit on the identity

Alternative: the standalone ratelimit API

Related