delete-permission

Remove a permission from your Unkey workspace using the CLI. Delete unused permissions to keep your RBAC authorization model clean and current.

Remove a permission from your workspace. This also removes the permission from all API keys and roles.

Important: This operation cannot be undone and immediately affects all API keys and roles that had this permission assigned. Any verification requests checking for the deleted permission will fail.

Required permissions:

• rbac.*.delete_permission

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api permissions delete-permission [flags]

Flags

--permission · string · required

The permission ID or slug to permanently delete from your workspace. Must be 3-255 characters, start with a letter, and contain only letters, numbers, dots, hyphens, and underscores.

WARNING: Deleting a permission has immediate and irreversible consequences:

• All API keys with this permission will lose that access immediately
• All roles containing this permission will have it removed
• Any verification requests checking for this permission will fail
• This action cannot be undone

Before deletion, ensure you have updated any keys or roles that depend on this permission, migrated to alternative permissions if needed, and notified affected users about the access changes.

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

Delete by permission ID

unkey api permissions delete-permission --permission=perm_1234567890abcdef

Output

Default output shows the request ID:

req_2c9a0jf23l4k567

{}

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

{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": {}
}