UNunkeyed
permissions

Create permission

Changed on

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 slugs must be unique within the workspace. Names do not need to be unique. Once created, permissions are immediately available for assignment.

Required Permissions

Your root key must have the following permission:

  • rbac.*.create_permission
post/v2/permissions.createPermission

Request

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/permissions.createPermission
  • Auth
    HTTP bearer

Request body

namestring required

Creates a permission with this human-readable name that describes its purpose. Use clear, semantic names that developers can easily understand when building authorization logic. Consider using hierarchical naming conventions like 'resource.action' for better organization.

Examples: 'users.read', 'billing.write', 'analytics.view', 'admin.manage'

slugstring required

Creates a URL-safe identifier for this permission that can be used 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. Should closely match the name but in a format suitable for technical usage. Must be unique within your workspace to ensure reliable permission lookups.

Keep slugs concise but descriptive for better developer experience.

descriptionstring

Provides 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 - designed for development teams and security audits.

Consider documenting:

  • What resources can be accessed
  • What operations are permitted
  • Any conditions or limitations
  • Related permissions that might be needed

Example request

{
  "name": "users.read",
  "slug": "users-read",
  "description": "Grants read-only access to user profile information, account settings, and subscription status."
}

Response

Permission created successfully

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "permissionId": "perm_1234567890abcdef"
  }
}

Changes

  • 59efaed65ec4Revision changes
    • warning

      changed the pattern of the request property from ^[a-zA-Z][a-zA-Z0-9._-]*$ to ^[a-zA-Z0-9_:\-\.\*]+$

  • 43ad1ce9a152Revision changes
    • info

      the endpoint scheme security bearer was added to the API

    • info

      the endpoint scheme security rootKey was removed from the API