Skip to main content
Create a new role to group related permissions for easier management. Roles enable consistent permission assignment across multiple API keys. Important: Role names must be unique within the workspace. Once created, roles are immediately available for assignment. Required permissions:
  • rbac.*.create_role
See the API reference for the full HTTP endpoint documentation.

​
Usage

unkey api permissions create-role [flags]

​
Flags

​
--name
string
required
The unique name for this role. Must be unique within your workspace and clearly indicate the role’s purpose. Use descriptive names like admin, editor, or billing_manager. Must be 1-512 characters, start with a letter, and contain only letters, numbers, dots, hyphens, and underscores.
​
--description
string
Provides comprehensive documentation of what this role encompasses and what access it grants. Include information about the intended use case, what permissions should be assigned, and any important considerations. This internal documentation helps team members understand role boundaries and security implications. Not visible to end users. Maximum 512 characters.

​
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 permissions create-role --name=content.editor --description="Can read and write content"

​
Output

Default output shows the request ID with latency, followed by the created role: 
req_2c9a0jf23l4k567 (took 45ms)

{
  "roleId": "role_5678efgh9012wxyz"
}
With --output=json, the full response envelope is returned: 
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": {
    "roleId": "role_5678efgh9012wxyz"
  }
}
Last modified on March 26, 2026