create-identity

Create an identity using the Unkey CLI to group multiple API keys under a single user, team, or organization entity in your workspace.

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
--body	string	Send this JSON string as the request body. You cannot combine it with request-building flags.

Examples

Basic

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

Output

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

req_01H9TQPP77V5E48E9SH0BG0ZQX

{
  "identityId": "id_1234567890abcdef"
}

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

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