v4

latestOpenAPI 3.1.1Apache 2.02026-07-31107278570.4 KB

Roles

Update role information

Modifies an existing role's properties including display name, description, permissions, and inheritance. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy. Only the fields you specify will be updated, leaving other properties unchanged. When updating permissions, the new list replaces all existing permissions for the role.

put/api/v1/roles/{role_name}

Path parameters

role_namestring required

Unique name identifier of the role to update. Must be alphanumeric with underscores, 1-64 characters.

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.

permissionsstring[]

List of permission names to assign to this role. When provided, this replaces all existing role-permission mappings. Permissions must exist in the current environment. Maximum 100 permissions per role.

Example request

{
  "description": "Can create, edit, publish, and approve content. Cannot delete content or manage user accounts.",
  "display_name": "Senior Content Editor",
  "extends": "content_editor",
  "permissions": [
    "read:content",
    "write:content",
    "publish:content",
    "approve:content"
  ]
}

Response

Role updated successfully. Returns the modified role object with updated 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"
      }
    ]
  }
}