Skip to main content
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 March 26, 2026