Skip to main content
Unkey Docs

remove-permissions

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

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 for the full HTTP endpoint documentation.

Usage#

Flags#

--key-idstringrequired#

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.

--permissionsstring[]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#

FlagTypeDescription
--root-keystringOverride root key ($UNKEY_ROOT_KEY)
--api-urlstringOverride API base URL (default: https://api.unkey.com)
--configstringPath to config file (default: ~/.unkey/config.toml)
--outputstringOutput format. Use json for raw JSON
--bodystringSend this JSON string as the request body. You cannot combine it with request-building flags.

Examples#

Output#

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

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

add-permissionsset-permissions