Skip to main content

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.

Update an identity’s metadata and rate limits. Only specified fields are modified, others remain unchanged. Use this for subscription changes, plan upgrades, or updating user information. Changes take effect immediately. Important:
  • Rate limit changes propagate within 30 seconds across all regions
  • Providing --meta-json replaces all existing metadata; omitting it preserves current metadata
  • Providing --ratelimits-json replaces all existing rate limits; omitting it preserves current rate limits
Required permissions:
  • identity.*.update_identity (to update identities in any workspace)
See the API reference for the full HTTP endpoint documentation.

​
Usage

unkey api identities update-identity [flags]

​
Flags

​
--identity
string
required
The ID of the identity to update. Accepts either the externalId (your system-generated identifier) or the identityId (internal identifier returned by the identity service).
​
--meta-json
string
JSON object of metadata to replace existing metadata. Omitting this flag preserves existing metadata, while providing an empty object '{}' clears all metadata. Avoid storing sensitive data here as it is returned in verification responses. Large metadata objects increase verification latency and should stay under 10KB total size.
​
--ratelimits-json
string
JSON array of rate limit configurations. Replaces all existing identity rate limits with this complete list. Omitting this flag preserves existing rate limits, while providing an empty array '[]' removes all rate limits. These limits are shared across all keys belonging to this identity, preventing abuse through multiple keys.

​
Global Flags

FlagTypeDescription
--root-keystringOverride root key ($UNKEY_ROOT_KEY)
--api-urlstringOverride API base URL (default: https://api.unkey.com)
--configstringPath to config file (default: ~/.unkey/config.toml)
--outputstringOutput format. Use json for raw JSON

​
Examples

unkey api identities update-identity --identity=user_123 --meta-json='{"plan":"premium","name":"Alice Smith"}'

​
Output

Default output shows the request ID with latency, followed by the updated identity: 
req_2c9a0jf23l4k567 (took 52ms)

{
  "id": "id_1234abcd",
  "externalId": "user_123",
  "meta": {
    "plan": "premium",
    "name": "Alice Smith"
  },
  "ratelimits": [
    {
      "id": "rl_5678efgh",
      "name": "requests",
      "limit": 1000,
      "duration": 3600000,
      "autoApply": true
    }
  ]
}
With --output=json, the full response envelope is returned: 
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": {
    "id": "id_1234abcd",
    "externalId": "user_123",
    "meta": {
      "plan": "premium",
      "name": "Alice Smith"
    },
    "ratelimits": [
      {
        "id": "rl_5678efgh",
        "name": "requests",
        "limit": 1000,
        "duration": 3600000,
        "autoApply": true
      }
    ]
  }
}
Last modified on May 6, 2026