# 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)

<Note>
See the [API reference](/api-reference/keys/set-key-roles) for the full HTTP endpoint documentation.
</Note>

## Usage

```bash
unkey api keys set-roles [flags]
```

## Flags

<ParamField body="--key-id" type="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.
</ParamField>

<ParamField body="--roles" type="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.
</ParamField>

## 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

<CodeGroup>
```bash Basic
unkey api keys set-roles --key-id=key_1234abcd --roles=api_admin,billing_reader
```
```bash Reset to a single role
unkey api keys set-roles --key-id=key_1234abcd --roles=viewer
```
```bash JSON output for scripting
unkey api keys set-roles --key-id=key_1234abcd --roles=api_admin,billing_reader --output=json
```
</CodeGroup>

## Output

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

```text
req_2c9a0jf23l4k567

[
  {
    "id": "role_1234567890abcdef",
    "name": "api_admin"
  },
  {
    "id": "role_abcdef1234567890",
    "name": "billing_reader"
  }
]
```

With `--output=json`, the full response envelope is returned:

```json
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": [
    {
      "id": "role_1234567890abcdef",
      "name": "api_admin"
    },
    {
      "id": "role_abcdef1234567890",
      "name": "billing_reader"
    }
  ]
}
```