v4

latestOpenAPI 3.1.1Apache 2.02026-07-31107278570.4 KB

Roles

Create new role in environment

Creates a new role within the environment with specified permissions and metadata. Use this endpoint to define custom roles that can be assigned to users or groups. You can create hierarchical roles by extending existing roles, assign specific permissions, and configure display information. Roles are the foundation of your access control system and determine what actions users can perform.

post/api/v1/roles

Request body

descriptionstring

Detailed description of the role's purpose, capabilities, and intended use cases. Maximum 2000 characters.

display_namestring

Human-readable display name for the role. Used in user interfaces, reports, and user-facing communications.

extendsstring

Name of the base role that this role extends. Enables hierarchical role inheritance where this role inherits all permissions from the base role.

namestring

Unique name identifier for the role. Must be alphanumeric with underscores, 1-64 characters. This name is used in API calls and cannot be changed after creation.

permissionsstring[]

List of permission names to assign to this role. Permissions must exist in the current environment. Maximum 100 permissions per role.

Example request

{
  "description": "Can create, edit, and publish content but cannot delete content or manage user accounts",
  "display_name": "Content Editor",
  "extends": "viewer",
  "name": "content_editor",
  "permissions": [
    "read:content",
    "write:content",
    "publish:content"
  ]
}

Response

Role created successfully. Returns the complete role object with system-generated ID and timestamps.

Example response

{
  "role": {
    "default_creator": true,
    "default_member": true,
    "dependent_roles_count": 3,
    "description": "Can create, edit, and publish content but cannot delete or manage users",
    "display_name": "Content Editor",
    "extends": "admin_role",
    "id": "role_1234abcd5678efgh",
    "is_org_role": true,
    "name": "content_editor",
    "permissions": [
      {
        "description": "Read Content",
        "name": "read:content",
        "role_name": "admin_role"
      },
      {
        "description": "Write Content",
        "name": "write:content",
        "role_name": "editor_role"
      }
    ]
  }
}