Skip to main content
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 edge propagation. 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

unkey api keys set-roles [flags]

​
Flags

​
--key-id
string
required
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.
​
--roles
string[]
required
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

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 keys set-roles --key-id=key_1234abcd --roles=api_admin,billing_reader

​
Output

Default output shows the request ID with latency, followed by the roles now assigned to the key: 
req_2c9a0jf23l4k567 (took 45ms)

[
  {
    "id": "role_1234567890abcdef",
    "name": "api_admin"
  },
  {
    "id": "role_abcdef1234567890",
    "name": "billing_reader"
  }
]
With --output=json, the full response envelope is returned: 
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": [
    {
      "id": "role_1234567890abcdef",
      "name": "api_admin"
    },
    {
      "id": "role_abcdef1234567890",
      "name": "billing_reader"
    }
  ]
}
Last modified on March 26, 2026