Replace all roles on a key with the specified set in a single atomic operation.
Use this to synchronize with external systems, reset roles to a known state, or apply standardized role templates. Direct permissions are never affected.
Important: Changes take effect immediately with up to 30-second propagation across regions. This is a wholesale replacement, not an incremental update -- any existing roles not included in the request are removed.
Required permissions:
api.*.update_key(to update keys in any API)api.<api_id>.update_key(to update keys in a specific API)
See the API reference for the full HTTP endpoint documentation.
Usage#
Flags#
The key ID to set roles on. This is the database identifier returned from key creation (e.g., key_2cGKbMxRyIzhCxo1Idjz8q), not the actual API key string that users include in requests.
Comma-separated list of roles. Replaces all existing roles on the key with this exact set. All roles must already exist in your workspace -- invalid role references cause the entire operation to fail atomically. Providing an empty value removes all role assignments from the 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 roles now assigned to the key:
With --output=json, the full response envelope is returned: