UNunkeyed
identities

Create Identity

Changed on

Create an identity to group multiple API keys under a single entity. Identities enable shared rate limits and metadata across all associated keys.

Perfect for users with multiple devices, organizations with multiple API keys, or when you need unified rate limiting across different services.

Important Requires identity.*.create_identity permission

post/v2/identities.createIdentity

Request

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/identities.createIdentity
  • Auth
    HTTP bearer

Request body

externalIdstring required

Creates an identity using your system's unique identifier for a user, organization, or entity. Must be stable and unique across your workspace - duplicate externalIds return CONFLICT errors. This identifier links Unkey identities to your authentication system, database records, or tenant structure.

Avoid changing externalIds after creation as this breaks the link between your systems. Use consistent identifier patterns across your application for easier management and debugging. Accepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats. Essential for implementing proper multi-tenant isolation and user-specific rate limiting.

metaobject

Stores arbitrary JSON metadata returned during key verification for contextual information. Eliminates additional database lookups during verification, improving performance for stateless services. Avoid storing sensitive data here as it's returned in verification responses.

Large metadata objects increase verification latency and should stay under 10KB total size. Use this for subscription details, feature flags, user preferences, and organization information. Metadata is returned as-is whenever keys associated with this identity are verified.

Example request

{
  "externalId": "user_123",
  "ratelimits": [
    {
      "name": "api"
    }
  ]
}

Response

Identity created successfully.

Example response

{
  "meta": {
    "requestId": "req_123"
  }
}

Changes