# remove-permissions

> Remove specific permissions from an API key using the Unkey CLI without affecting other roles or permissions. Revoke granular access rights.

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

Use this for privilege downgrades, removing temporary access, or plan changes that revoke specific capabilities. Permissions granted through roles 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 permission changes available for verification within 30 seconds across all regions.

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

## Usage

```bash
unkey api keys remove-permissions [flags]
```

## Flags

<ParamField body="--key-id" type="string" required>
The key ID to remove permissions from. This is the database identifier returned from `keys.createKey`, do not confuse it with the actual API key string that users include in requests.
</ParamField>

<ParamField body="--permissions" type="string[]" required>
Comma-separated list of permission names to remove. You can specify permissions by slug or by permission ID. After removal, verification checks for these permissions will fail unless granted through roles.
</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 remove-permissions --key-id=key_1234abcd --permissions=documents.read,documents.write
```
```bash JSON output for scripting
unkey api keys remove-permissions --key-id=key_1234abcd --permissions=documents.read --output=json
```
```bash Remove a single permission
unkey api keys remove-permissions --key-id=key_1234abcd --permissions=billing.manage
```
</CodeGroup>

## Output

Default output shows the request ID, followed by the remaining direct permissions on the key:

```text
req_2c9a0jf23l4k567

[
  {
    "id": "perm_1234abcd",
    "name": "documents.read"
  }
]
```

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

```json
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": [
    {
      "id": "perm_1234abcd",
      "name": "documents.read"
    }
  ]
}
```