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

# Overview

> Group multiple API keys under a single identity like a user, team, or organization. Manage shared configuration and rate limits in Unkey.

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:

```ts theme={"theme":"kanagawa-wave"}
// Create an identity for the customer
try {
  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:

```ts theme={"theme":"kanagawa-wave"}
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

<AccordionGroup>
  <Accordion title="Share rate limits across keys" icon="gauge">
    Set a rate limit on the identity, and all associated keys share the same
    pool. If a user has 1000 requests/hour across all their keys, they can't
    bypass the limit by using different keys. [Learn more
    →](/platform/identities/ratelimits)
  </Accordion>

  <Accordion title="Aggregate analytics per customer" icon="chart-pie">
    Instead of piecing together usage from individual keys, get total usage per
    identity. Perfect for billing dashboards and customer insights.
  </Accordion>

  <Accordion title="Centralized configuration" icon="sliders">
    Store plan tier, feature flags, or custom limits on the identity. All keys
    inherit this configuration without needing individual updates.
  </Accordion>

  <Accordion title="Multi-tenant organizations" icon="building">
    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.
  </Accordion>
</AccordionGroup>

## Data model

<ParamField body="id" type="string" required>
  Unkey's internal identifier for this identity. Use this to reference the
  identity in API calls.
</ParamField>

<ParamField body="externalId" type="string" required>
  **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.

  ```ts theme={"theme":"kanagawa-wave"}
  // Example with Clerk
  const identity = await unkey.identities.createIdentity({
    externalId: clerkUserId,  // "user_2NNEqL2nrIRdJ194ndJqAHwEfxC"
  });
  ```
</ParamField>

<ParamField body="meta" type="json">
  Arbitrary JSON metadata. Store anything useful: plan tier, feature flags, company name, etc.

  ```json theme={"theme":"kanagawa-wave"}
  {
    "plan": "enterprise",
    "features": ["advanced-analytics", "sso"],
    "billingEmail": "billing@acme.com"
  }
  ```
</ParamField>

## Next steps

<CardGroup cols={2}>
  <Card title="Shared rate limits" icon="gauge-high" href="/platform/identities/ratelimits">
    Enforce limits across all keys for an identity
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart/identities/shared-ratelimits">
    Step-by-step guide to implementing identities
  </Card>
</CardGroup>