Skip to main content
Create a new permission to define specific actions or capabilities in your RBAC system. Permissions can be assigned directly to API keys or included in roles. Use hierarchical naming patterns like documents.read, admin.users.delete, or billing.invoices.create for clear organization. Important: Permission names must be unique within the workspace. Once created, permissions are immediately available for assignment. Required permissions:
  • rbac.*.create_permission
See the API reference for the full HTTP endpoint documentation.

​
Usage

unkey api permissions create-permission [flags]

​
Flags

​
--name
string
required
Human-readable name describing the permission’s purpose. Names must be unique within your workspace to prevent conflicts during assignment. Use clear, semantic names that developers can easily understand when building authorization logic. Consider using hierarchical naming conventions like resource.action for better organization. Must be 1-512 characters.
​
--slug
string
required
URL-safe identifier for use in APIs and integrations. Must start with a letter and contain only letters, numbers, periods, underscores, and hyphens. Slugs are often used in REST endpoints, configuration files, and external integrations. Must be unique within your workspace. Must be 1-128 characters.
​
--description
string
Detailed documentation of what this permission grants access to. Include information about affected resources, allowed actions, and any important limitations. This internal documentation helps team members understand permission scope and security implications. Not visible to end users. Max 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-permission --name=users.read --slug=users-read

​
Output

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

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