Skip to main content
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 edge propagation. 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

​
--key-id
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.
​
--permissions
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

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

​
Examples

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

​
Output

Default output shows the request ID with latency, followed by the remaining direct permissions on the key: 
req_2c9a0jf23l4k567 (took 45ms)

[
  {
    "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"
    }
  ]
}
Last modified on March 26, 2026