Sign in

e171c13af8aa

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

Create role

Create a new role to group related permissions for easier management. Roles enable consistent permission assignment across multiple API keys. Permission slugs supplied in permissions are attached during creation. Missing permissions are created automatically.

Important: Role names must be unique within the workspace. Once created, roles are immediately available for assignment.

Required Permissions

Your root key must always have:

  • rbac.*.create_role

When permissions is not empty, it must also have:

  • rbac.*.add_permission_to_role

When any requested permission slug does not exist, it must also have:

  • rbac.*.create_permission
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', 'Billing Manager'

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
permissionsstring[]

Permission slugs to attach to the role. Existing permissions are reused. Missing permissions are created automatically when the root key has rbac.*.create_permission.

Omit this field or provide an empty array to create the role without permissions.

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"
  }
}