Update a custom role's name, description, or capabilities. System roles cannot be modified. Requires the manage_roles capability.
When capabilities are updated, changes take effect immediately for all users assigned to this role. The calling user can only set capabilities they themselves possess (anti-escalation).
organization_id string required
Organization ID (org_ prefixed string).
role_id string required
Role ID (role_ prefixed string). Must be a custom role.
name string optional
New role name. Must be unique within the organization. Max 100 characters.
description string optional
New description. Max 500 characters.
capabilities array of strings optional
Complete list of capabilities. Replaces all existing capabilities. At least one capability required.
The updated role object with current capabilities and member count.
- Bash
- Python
- Python
- JavaScript
curl -X PATCH "https://api.aitronos.com/v1/organizations/org_abc123/roles/role_xyz789" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Marketing Lead",
"description": "Updated description",
"capabilities": ["view_audit_log", "manage_knowledge_slices", "invite_users"]
}'