> ## Documentation Index
> Fetch the complete documentation index at: https://unkey.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# remove-roles

> Remove specific roles from an API key using the Unkey CLI without affecting direct permissions or other assigned roles on the same key.

Remove roles from a key without affecting direct permissions or other roles.

Use this for privilege downgrades, removing temporary access, or subscription changes that revoke specific role-based capabilities. Direct permissions remain unchanged.

**Important:** Changes take effect immediately with up to 30-second propagation across regions.

**Required permissions:**

* `api.*.update_key` (to update keys in any API)
* `api.<api_id>.update_key` (to update keys in a specific API)

**Side effects:** Invalidates the key cache for immediate effect, and makes role changes available for verification within 30 seconds across all regions.

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

## Usage

```bash theme={"theme":"kanagawa-wave"}
unkey api keys remove-roles [flags]
```

## Flags

<ParamField body="--key-id" type="string" required>
  The key ID to remove roles from. This is the database identifier returned from key creation, do not confuse it with the actual API key string that users include in requests. Removing roles only affects direct assignments, not permissions inherited from other sources. Role changes take effect immediately but may take up to 30 seconds to propagate across all regions.
</ParamField>

<ParamField body="--roles" type="string[]" required>
  Comma-separated list of role names to remove. Operations are idempotent, removing non-assigned roles has no effect and causes no errors. After removal, the key loses access to permissions that were only granted through these roles. Invalid role references cause the entire operation to fail atomically, ensuring consistent state.
</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                   |

## Examples

<CodeGroup>
  ```bash Basic theme={"theme":"kanagawa-wave"}
  unkey api keys remove-roles --key-id=key_1234abcd --roles=api_admin,billing_reader
  ```

  ```bash JSON output for scripting theme={"theme":"kanagawa-wave"}
  unkey api keys remove-roles --key-id=key_1234abcd --roles=api_admin --output=json
  ```

  ```bash Remove a single role theme={"theme":"kanagawa-wave"}
  unkey api keys remove-roles --key-id=key_1234abcd --roles=temporary_access
  ```
</CodeGroup>

## Output

Default output shows the request ID with latency, followed by the remaining roles assigned to the key:

```text theme={"theme":"kanagawa-wave"}
req_2c9a0jf23l4k567 (took 45ms)

[
  {
    "id": "role_5678efgh",
    "name": "billing_reader"
  }
]
```

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

```json theme={"theme":"kanagawa-wave"}
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": [
    {
      "id": "role_5678efgh",
      "name": "billing_reader"
    }
  ]
}
```