Skip to main content
Unkey Docs

create-role

Create a new role using the Unkey CLI to group related permissions together. Simplify access management by assigning roles instead of permissions.
2 min read

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
Note

See the API reference for the full HTTP endpoint documentation.

Usage#

Flags#

--namestringrequired#

The unique name for this role. Must be unique within your workspace and clearly indicate the role's purpose. Use a descriptive name like admin, content.editor, or Billing Manager. Must be 1-128 characters.

--descriptionstring#

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.

--permissionsstring[]#

Comma-separated permission slugs to attach to the role. Missing permissions are created automatically when the root key has permission to create them.

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
--bodystringSend this JSON string as the request body. You cannot combine it with request-building flags.

Examples#

Output#

Default output shows the request ID, followed by the created role:

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

list-permissionsdelete-role