Overview - Unkey Docs

Identities let you connect multiple API keys to a single entity, a user, an organization, a service account, or anything else in your system. Once connected, keys can share configuration, metadata, and rate limits.

Why use identities?#

Without identities, each API key is standalone. If a user has 3 keys, you need to update each one individually. With identities:

Without Identities	With Identities
Update rate limits on each key separately	Update once on the identity, applies to all keys
Metadata stored per-key	Shared metadata across all keys
Analytics scattered across keys	Aggregated analytics per identity
No concept of "this user's total usage"	Shared rate limit pool across all keys

Real-world example#

Imagine you're building a developer platform like Stripe. Each customer might have:

A test key for development
A production key for live traffic
Multiple restricted keys for different services

All these keys belong to the same customer. With identities:

// Create an identity for the customertry {  await unkey.identities.createIdentity({    externalId: "customer_acme_123", // Your internal customer ID    meta: {      plan: "pro",      company: "Acme Corp",    },  });  // Keys link to the identity by reusing the same externalId  await unkey.keys.createKey({    apiId: "api_xxx",    externalId: "customer_acme_123",    name: "Production Key",  });  await unkey.keys.createKey({    apiId: "api_xxx",    externalId: "customer_acme_123",    name: "Test Key",  });} catch (err) {  console.error(err);  throw err;}

Now when you verify any of these keys, you get the identity metadata:

const { meta, data } = await unkey.keys.verifyKey({ key: "sk_..." });console.log(data.identity);// { id: "id_xxx", externalId: "customer_acme_123", meta: { plan: "pro", company: "Acme Corp" } }

Use cases#

Aggregate analytics per customer

Instead of piecing together usage from individual keys, get total usage per identity. Perfect for billing dashboards and customer insights.

Centralized configuration

Store plan tier, feature flags, or custom limits on the identity. All keys inherit this configuration without needing individual updates.

Multi-tenant organizations

Map identities to organizations in your system. When an org adds team members or creates new keys, they all share the same identity and limits.

Data model#

idstringrequired#

Unkey's internal identifier for this identity. Use this to reference the identity in API calls.

externalIdstringrequired#

Your identifier for this entity. This links the Unkey identity to your system, typically a user ID, org ID, or customer ID.

If you use Clerk, Auth0, WorkOS, or similar: use their user/org ID as the externalId.

// Example with Clerkconst identity = await unkey.identities.createIdentity({  externalId: clerkUserId,  // "user_2NNEqL2nrIRdJ194ndJqAHwEfxC"});

metajson#

Arbitrary JSON metadata. Store anything useful: plan tier, feature flags, company name, etc.

{  "plan": "enterprise",  "features": ["advanced-analytics", "sso"],  "billingEmail": "billing@acme.com"}

Next steps#

Shared rate limits

Enforce limits across all keys for an identity

Quickstart

Step-by-step guide to implementing identities