Skip to main content

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 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

​
--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 May 6, 2026