delete-role

Remove a role from your Unkey workspace using the CLI. Delete unused roles and automatically unlink them from all associated API keys.

Remove a role from your workspace. This also removes the role from all assigned API keys.

Important: This operation cannot be undone and immediately affects all API keys that had this role assigned. All keys with this role will lose the associated permissions, and access to resources protected by this role’s permissions will be denied.

Required permissions:

• rbac.*.delete_role

See the API reference for the full HTTP endpoint documentation.

Usage

unkey api permissions delete-role [flags]

Flags

--role · string · required

The role ID or name to permanently delete. Must either be a valid role ID that begins with role_ or a role name that exists within your workspace. Must be 3-255 characters and contain only letters, numbers, underscores, colons, hyphens, dots, and asterisks.

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

Basic

unkey api permissions delete-role --role=role_dns_manager

Output

Default output shows the request ID:

req_2c9a0jf23l4k567

{}

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

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