The Roles Service provides endpoints for creating, managing, and assigning roles and permissions within organizations. It implements a robust role-based access control (RBAC) system that allows fine-grained control over user permissions.
Authentication All endpoints require a valid Bearer token in the Authorization header.
Base URL Endpoints Overview
Endpoint Method Description /api/roles/createPOST Create a custom role /api/roles/updatePUT Update a custom role /api/roles/removeDELETE Delete a custom role /api/roles/list_rolesGET List all roles for an organization /api/roles/permissionPOST Create a new permission /api/roles/permissionDELETE Delete a permission /api/roles/list_permissionsGET List all available permissions
Role Endpoints Create Role Create a new custom role within an organization.
Request
Python
JavaScript
Response
curl -X POST "{{baseUrl}}/api/roles/create?org_id=your-org-id" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Content Manager", "description": "Manages content and knowledge bases", "hierarchy_level": 40, "permission_ids": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a" ] }'
Endpoint: POST /api/roles/createQuery Parameters:
Parameter Required Description org_idYes Organization ID
Request Body:
Field Type Required Description namestring Yes Role name (must be unique within organization) descriptionstring No Role description hierarchy_levelinteger Yes Role hierarchy level (0-100, higher = more privileges) permission_idsarray Yes List of permission IDs to assign to the role
Requires roles:write permission. System roles (owner, admin, member, guest) cannot be created this way - they are automatically created with each organization.
Update Role Update an existing custom role.
Request
Python
JavaScript
Response
curl -X PUT "{{baseUrl}}/api/roles/update?org_id=your-org-id&role_id=1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Senior Content Manager", "description": "Manages content with elevated permissions", "hierarchy_level": 50, "permission_ids": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6", "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a", "7d6c5b4a-3f2e-1d0c-9b8a-7f6e5d4c3b2a" ] }'
Endpoint: PUT /api/roles/updateQuery Parameters:
Parameter Required Description org_idYes Organization ID role_idYes Role ID to update
Request Body: All fields are optional - only include fields you want to update:
Field Type Required Description namestring No New role name descriptionstring No New role description hierarchy_levelinteger No New hierarchy level permission_idsarray No Updated list of permission IDs (replaces existing permissions)
System roles (owner, admin, member, guest) cannot be updated. Only custom roles created via the API can be modified.
Delete Role Delete a custom role from an organization.
Request
Python
JavaScript
Response
curl -X DELETE "{{baseUrl}}/api/roles/remove?org_id=your-org-id&role_id=1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p" \ -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: DELETE /api/roles/removeQuery Parameters:
Parameter Required Description org_idYes Organization ID role_idYes Role ID to delete
System roles cannot be deleted
Roles assigned to members cannot be deleted (reassign members first)
This action cannot be undone
List Roles Retrieve all roles for an organization (includes both system roles and custom roles).
Request
Python
JavaScript
Response
curl -X GET "{{baseUrl}}/api/roles/list_roles?org_id=your-org-id" \ -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/roles/list_rolesQuery Parameters:
Parameter Required Description org_idYes Organization ID
Returns both system roles (owner, admin, member, guest) and organization-specific custom roles. System roles have is_system_role: true and organization_id: null.
Permission Endpoints List All Permissions Retrieve all available permissions in the system.
Request
Python
JavaScript
Response
curl -X GET "{{baseUrl}}/api/roles/list_permissions" \ -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: GET /api/roles/list_permissionsThis returns all system-wide permissions. Use these permission IDs when creating or updating roles.
Create Permission Create a new system-wide permission.
Request
Python
JavaScript
Response
curl -X POST "{{baseUrl}}/api/roles/permission" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "reports:generate", "description": "Can generate reports" }'
Endpoint: POST /api/roles/permissionRequest Body:
Field Type Required Description namestring Yes Permission name (format: resource:action) descriptionstring No Permission description
Permissions follow the resource:action naming convention (e.g., kb:read, agent:execute, *:admin).
Delete Permission Delete a permission from the system.
curl -X DELETE "{{baseUrl}}/api/roles/permission?permission_id=a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6" \ -H "Authorization: Bearer YOUR_TOKEN"
Endpoint: DELETE /api/roles/permissionQuery Parameters:
Parameter Required Description permission_idYes Permission ID to delete
Deleting a permission will remove it from all roles that have it assigned. This action cannot be undone.
Managing User Roles To assign or update a user’s role within an organization, use the Users Service endpoints:
Update User Role : PUT /api/users/update - Change a user’s role (requires owner permission)List Users : GET /api/users/list - See all users and their roles in an organization
See the Users Service API documentation for details.
Error Responses
Status Code Description 400 Bad Request - Invalid input, role name conflict, or system role modification attempt 401 Unauthorized - Invalid or missing token 403 Forbidden - Insufficient permissions 404 Not Found - Role or permission doesn’t exist 500 Internal Server Error - Server-side error
Implementation Notes System Roles Four system roles are automatically created with each organization:
Role Level Description Can Modify? owner 100 Full system access No admin 80 Administrative capabilities No member 20 Standard user access No guest 10 Limited access No
System roles cannot be created, updated, or deleted via the API.
Custom Roles
Custom roles are organization-specific
Hierarchy levels determine role precedence (0-100)
Higher levels generally have more privileges
Role names must be unique within an organization
Roles assigned to members cannot be deleted
Permissions follow the resource:action pattern:
Resources : kb, conversation, agent, tool, organization, users, rolesActions : read, write, delete, admin, executeWildcards : *:read (read all resources), kb:* (all kb actions), *:* (full access)
Required Permissions
Create/Update/Delete Roles : Requires roles:write permissionDelete Roles : Requires roles:delete permissionView Roles : Requires roles:read permissionManage Permissions : Requires system-level admin access 
