v4

latestOpenAPI 3.1.1Apache 2.02026-07-31107278570.4 KB

Roles

Update organization role

Modifies an existing organization role's properties including display name, description, permissions, and inheritance settings. Use this endpoint to update role metadata, change permission assignments, or modify role hierarchy within the organization. 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/organizations/{org_id}/roles/{role_name}

Path parameters

org_idstring required

Unique identifier of the organization

role_namestring required

Unique name of the role

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

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