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

/api/roles

​
Role Endpoints

​
Create Role

Create a new role within an organization.

curl -X POST {{baseUrl}}/api/roles/create?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project Manager",
    "description": "Manages projects and team assignments",
    "hierarchy_level": 50,
    "permission_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a"
    ]
  }'

Endpoint: POST /api/roles/create

Query Parameters:

ParameterRequiredDescription
org_idYesOrganization ID

Request Body:

FieldTypeRequiredDescription
namestringYesRole name
descriptionstringNoRole description
hierarchy_levelintegerYesRole hierarchy level (higher number = higher privileges)
permission_idsarrayYesList of permission IDs to assign to the role

​
List Roles

Retrieve all roles for an organization.

curl -X GET {{baseUrl}}/api/roles/list?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/roles/list

Query Parameters:

ParameterRequiredDescription
org_idYesOrganization ID

​
Get Role

Retrieve details about a specific role.

curl -X GET {{baseUrl}}/api/roles/get?role_id=1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/roles/get

Query Parameters:

ParameterRequiredDescription
role_idYesRole ID

​
Update Role

Update an existing role.

curl -X PUT {{baseUrl}}/api/roles/update?role_id=1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Project Manager",
    "description": "Manages complex projects and coordinates multiple teams",
    "hierarchy_level": 60,
    "permission_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a",
      "7d6c5b4a-3f2e-1d0c-9b8a-7f6e5d4c3b2a"
    ]
  }'

Endpoint: PUT /api/roles/update

Query Parameters:

ParameterRequiredDescription
role_idYesRole ID

Request Body:

FieldTypeRequiredDescription
namestringNoNew role name
descriptionstringNoNew role description
hierarchy_levelintegerNoNew hierarchy level
permission_idsarrayNoUpdated list of permission IDs

​
Delete Role

Delete a role from an organization.

curl -X DELETE {{baseUrl}}/api/roles/delete?role_id=1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: DELETE /api/roles/delete

Query Parameters:

ParameterRequiredDescription
role_idYesRole ID

​
Permission Endpoints

​
List All Permissions

Retrieve all available permissions in the system.

curl -X GET {{baseUrl}}/api/roles/list_permissions \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/roles/list_permissions

​
Get Permissions for Role

Retrieve all permissions assigned to a specific role.

curl -X GET {{baseUrl}}/api/roles/get_permissions?role_id=1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/roles/get_permissions

Query Parameters:

ParameterRequiredDescription
role_idYesRole ID

​
Update Role Permissions

Update the permissions assigned to a role.

curl -X PUT {{baseUrl}}/api/roles/update_permissions?role_id=1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permission_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a",
      "7d6c5b4a-3f2e-1d0c-9b8a-7f6e5d4c3b2a"
    ]
  }'

Endpoint: PUT /api/roles/update_permissions

Query Parameters:

ParameterRequiredDescription
role_idYesRole ID

Request Body:

FieldTypeRequiredDescription
permission_idsarrayYesArray of permission IDs to assign to the role

​
User Role Endpoints

​
Assign Role to User

Assign a role to a user within an organization.

curl -X POST {{baseUrl}}/api/roles/assign?org_id=your-org-id \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "5e6f7g8h-9i0j-1k2l-3m4n-5o6p7q8r9s0t",
    "role_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
  }'

Endpoint: POST /api/roles/assign

Query Parameters:

ParameterRequiredDescription
org_idYesOrganization ID

Request Body:

FieldTypeRequiredDescription
user_idstringYesUser ID
role_idstringYesRole ID

​
Get User’s Role

Retrieve a user’s role within an organization.

curl -X GET {{baseUrl}}/api/roles/get_user_role?org_id=your-org-id&user_id=5e6f7g8h-9i0j-1k2l-3m4n-5o6p7q8r9s0t \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: GET /api/roles/get_user_role

Query Parameters:

ParameterRequiredDescription
org_idYesOrganization ID
user_idYesUser ID

​
Remove User Role

Remove a user’s role within an organization.

curl -X DELETE {{baseUrl}}/api/roles/remove_user_role?org_id=your-org-id&user_id=5e6f7g8h-9i0j-1k2l-3m4n-5o6p7q8r9s0t \
  -H "Authorization: Bearer YOUR_TOKEN"

Endpoint: DELETE /api/roles/remove_user_role

Query Parameters:

ParameterRequiredDescription
org_idYesOrganization ID
user_idYesUser ID

​
Error Responses

Status CodeDescription
400Bad Request - Invalid input or validation error
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions
404Not Found - Role or permission doesn’t exist
409Conflict - Role already exists with the given name
500Internal Server Error - Server-side error

​
Implementation Notes

  • The Roles Service implements a hierarchical role-based access control (RBAC) system
  • Roles have hierarchy levels to determine precedence (higher number = higher privileges)
  • Permissions follow a resource:action naming convention
  • Default roles (Owner, Admin, Member) are created automatically when an organization is created
  • Users can only have one role per organization
  • Only users with appropriate permissions can manage roles (typically Owners and Admins)
  • The Owner role cannot be deleted or modified
  • Roles with higher hierarchy levels cannot be modified by users with lower hierarchy roles