set-roles

Replace all roles on an API key using the Unkey CLI in a single atomic operation. Overwrite existing role assignments with a new exact set.

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

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

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

Basic

unkey api keys set-roles --key-id=key_1234abcd --roles=api_admin,billing_reader

Output

Default output shows the request ID, followed by the roles now assigned to the key:

req_2c9a0jf23l4k567

[
  {
    "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"
    }
  ]
}