Sign in

v66

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0174265626.3 KB
permissions

Create role

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

Your root key must have the following permission:

  • rbac.*.create_role
post/v2/permissions.createRole

Request body

namestring 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'.

Examples: 'admin.billing', 'support.readonly', 'developer.api', 'manager.analytics'

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 - designed for administration teams and access control audits.

Consider documenting:

  • The role's intended purpose and scope
  • What types of users should receive this role
  • What permissions are typically associated with it
  • Any security considerations or limitations
  • Related roles that might be used together

Example request

{
  "name": "support.readonly",
  "description": "Provides read-only access for customer support representatives. Includes permissions to view user accounts, support tickets, and basic analytics. Does not include access to billing, admin functions, or data modification capabilities."
}

Response

Role created successfully

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {
    "roleId": "role_1234567890abcdef"
  }
}