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
--metareplaces all existing metadata; omitting it preserves current metadata - Providing
--ratelimitsreplaces 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#
Flags#
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).
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.
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.
Show Rate limit object propertiesHide Rate limit object properties
The name of this rate limit. Used to identify which limit to check during key verification. Use descriptive, semantic names like api_requests, heavy_operations, or downloads. You will reference this exact name when verifying keys to check against this specific limit.
The maximum number of operations allowed within the specified time window. When this limit is reached, verification requests will fail with code=RATE_LIMITED until the window resets.
The duration for each rate limit window in milliseconds. Common values: 1000 (1 second), 60000 (1 minute), 3600000 (1 hour), 86400000 (24 hours).
Whether this rate limit should be automatically applied when verifying a key.
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#
Output#
Default output shows the request ID, followed by the updated identity:
With --output=json, the full response envelope is returned: