Skip to main content
You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys. See Permission reference for every permission.
Create a role. A role groups permissions so you can give a key many at once. Calls POST /v2/permissions.createRole. See Roles and permissions.

​
Usage

​
Flags

​
string
required
Role name, 1 to 128 characters. Unique per workspace. Reusing one returns 409 err:unkey:data:role_already_exists. Keys refer to roles by name.
​
string
What the role is for.
​
string[]
Comma-separated permission slugs to attach. Slugs that don’t exist yet are created. Each slug is 1 to 128 characters matching ^[a-zA-Z0-9_:\-\.\*]+$, the same as create-permission.

​
Shared flags

Every unkey api command takes these. See CLI output and shared flags.
​
string
Root key used for the request. Falls back to UNKEY_ROOT_KEY, then to the key stored by unkey auth login.
​
string
default:"https://api.unkey.com"
Base URL of the API. Falls back to UNKEY_API_BASE_URL. You don’t normally need to set it.
​
string
default:"~/.unkey/config.toml"
Path of the config file written by unkey auth login. Falls back to UNKEY_CONFIG.
​
string
Output format. Falls back to UNKEY_OUTPUT. json prints the full response. Any other value prints the request ID and data.
​
string
Send this JSON as the whole request body instead of using the command’s flags. You can’t combine it with them.

​
Required permissions

rbac.*.create_role, plus rbac.*.add_permission_to_role when --permissions is given. Creating new slugs also needs rbac.*.create_permission. See Root key permissions.

​
Examples

Create with permissions
Or send the whole request as JSON:
Raw body
Last modified on September 29, 2026