> ## 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-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 theme={"theme":"kanagawa-wave"}
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                   |

## Examples

<CodeGroup>
  ```bash Basic theme={"theme":"kanagawa-wave"}
  unkey api keys remove-permissions --key-id=key_1234abcd --permissions=documents.read,documents.write
  ```

  ```bash JSON output for scripting theme={"theme":"kanagawa-wave"}
  unkey api keys remove-permissions --key-id=key_1234abcd --permissions=documents.read --output=json
  ```

  ```bash Remove a single permission theme={"theme":"kanagawa-wave"}
  unkey api keys remove-permissions --key-id=key_1234abcd --permissions=billing.manage
  ```
</CodeGroup>

## Output

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

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

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

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

```json theme={"theme":"kanagawa-wave"}
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": [
    {
      "id": "perm_1234abcd",
      "name": "documents.read"
    }
  ]
}
```