create-identity

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: External IDs must be unique within your workspace. Attempting to create an identity with a duplicate external ID returns a 409 Conflict error. Required permissions:

identity.*.create_identity

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api identities create-identity [flags]

Flags

--external-id

string

required

Your system’s unique identifier for the user, organization, or entity. Must be unique across your workspace --- duplicate external IDs return a 409 Conflict error. This identifier links Unkey identities to your authentication system, database records, or tenant structure. Accepts letters, numbers, underscores, dots, and hyphens (1—255 characters).

--meta-json

string

JSON object of arbitrary metadata stored on the identity. This metadata is returned during key verification, eliminating additional database lookups for contextual information. Useful for subscription details, feature flags, user preferences, and organization information. Avoid storing sensitive data as it is returned in verification responses.

Show JSON structure

<key>

any

Arbitrary key-value pairs. Values can be strings, numbers, booleans, arrays, or nested objects. Maximum of 100 properties. Keep total size under 10KB for optimal verification latency.

--ratelimits-json

string

JSON array of shared rate limit configurations for all keys under this identity. Rate limit counters are shared across all keys belonging to this identity, preventing abuse by users with multiple keys. Each named limit can have different thresholds and windows. Maximum of 50 rate limit configurations.

Show Array item properties

name

string

required

The name of this rate limit, used to identify which limit to check during key verification. Use descriptive names like api_requests, heavy_operations, or downloads. Must be 3—128 characters.

limit

integer

required

The maximum number of operations allowed within the specified time window. When reached, verification requests fail with code=RATE_LIMITED until the window resets.

duration

integer

required

The duration for each rate limit window in milliseconds. Common values: 1000 (1 second), 60000 (1 minute), 3600000 (1 hour), 86400000 (24 hours). Minimum 1000.

autoApply

boolean

default:false

Whether this rate limit should be automatically applied when verifying a key. Defaults to false.

Global Flags

Flag	Type	Description
`--root-key`	string	Override root key (`$UNKEY_ROOT_KEY`)
`--api-url`	string	Override API base URL (default: `https://api.unkey.com`)
`--config`	string	Path to config file (default: `~/.unkey/config.toml`)
`--output`	string	Output format — use `json` for raw JSON

Examples

unkey api identities create-identity --external-id=user_123

Output

Default output shows the request ID with latency, followed by the created identity:

req_01H9TQPP77V5E48E9SH0BG0ZQX (took 45ms)

{
  "identityId": "id_1234567890abcdef"
}

With --output=json, the full response envelope is returned:

{
  "meta": {
    "requestId": "req_01H9TQPP77V5E48E9SH0BG0ZQX"
  },
  "data": {
    "identityId": "id_1234567890abcdef"
  }
}

Getting Started

Changelog

Framework Guides

Cookbook

API Keys

Rate Limiting

Identities

Analytics

Audit Logs

Security

AI Code Gen

CLI

Migrations

Errors

Usage

Flags

Global Flags

Examples

Output

Getting Started

Changelog

Framework Guides

Cookbook

API Keys

Rate Limiting

Identities

Analytics

Audit Logs

Security

AI Code Gen

CLI

Migrations

Errors

​Usage

​Flags

​Global Flags

​Examples

​Output

Usage

Flags

Global Flags

Examples

Output