remove-permissions

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.

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api keys remove-permissions [flags]

Flags

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.

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.

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

unkey api keys remove-permissions --key-id=key_1234abcd --permissions=documents.read,documents.write

unkey api keys remove-permissions --key-id=key_1234abcd --permissions=documents.read --output=json

unkey api keys remove-permissions --key-id=key_1234abcd --permissions=billing.manage

Output

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

req_2c9a0jf23l4k567

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

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

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

Getting Started

Platform

Build & Deploy

Networking

Observability

CLI

Security

Keyspaces

AI Code Gen

Audit Logs

CLI

Errors

Usage

Flags

Global Flags

Examples

Output

​Usage

​Flags

​Global Flags

​Examples

​Output

Usage

Flags

Global Flags

Examples

Output