Roles Service API

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

Endpoints Overview

Endpoint	Method	Description
`/api/roles/create`	POST	Create a custom role
`/api/roles/update`	PUT	Update a custom role
`/api/roles/remove`	DELETE	Delete a custom role
`/api/roles/list_roles`	GET	List all roles for an organization
`/api/roles/permission`	POST	Create a new permission
`/api/roles/permission`	DELETE	Delete a permission
`/api/roles/list_permissions`	GET	List all available permissions

Role Endpoints

Create Role

Create a new custom 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": "Content Manager",
    "description": "Manages content and knowledge bases",
    "hierarchy_level": 40,
    "permission_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a"
    ]
  }'

import requests

url = "{{baseUrl}}/api/roles/create"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
params = {"org_id": "your-org-id"}
data = {
    "name": "Content Manager",
    "description": "Manages content and knowledge bases",
    "hierarchy_level": 40,
    "permission_ids": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a"
    ]
}

response = requests.post(url, headers=headers, params=params, json=data)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/roles/create";
const headers = {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
};
const params = { org_id: "your-org-id" };
const data = {
    name: "Content Manager",
    description: "Manages content and knowledge bases",
    hierarchy_level: 40,
    permission_ids: [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a"
    ]
};

axios.post(url, data, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

{
  "id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "name": "Content Manager",
  "description": "Manages content and knowledge bases",
  "hierarchy_level": 40,
  "organization_id": "your-org-id",
  "is_system_role": false,
  "created_at": "2023-08-01T10:00:00Z",
  "updated_at": "2023-08-01T10:00:00Z",
  "permissions": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "kb:read",
      "description": "Can view knowledge bases"
    },
    {
      "id": "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a",
      "name": "kb:write",
      "description": "Can create and edit knowledge bases"
    }
  ]
}

Endpoint: POST /api/roles/create Query Parameters:

Parameter	Required	Description
`org_id`	Yes	Organization ID

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Role name (must be unique within organization)
`description`	string	No	Role description
`hierarchy_level`	integer	Yes	Role hierarchy level (0-100, higher = more privileges)
`permission_ids`	array	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.

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

import requests

url = "{{baseUrl}}/api/roles/update"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
params = {
    "org_id": "your-org-id",
    "role_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
}
data = {
    "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"
    ]
}

response = requests.put(url, headers=headers, params=params, json=data)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/roles/update";
const headers = {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
};
const params = {
    org_id: "your-org-id",
    role_id: "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
};
const data = {
    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"
    ]
};

axios.put(url, data, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

{
  "id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "name": "Senior Content Manager",
  "description": "Manages content with elevated permissions",
  "hierarchy_level": 50,
  "organization_id": "your-org-id",
  "is_system_role": false,
  "created_at": "2023-08-01T10:00:00Z",
  "updated_at": "2023-08-05T14:30:00Z",
  "permissions": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "kb:read",
      "description": "Can view knowledge bases"
    },
    {
      "id": "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a",
      "name": "kb:write",
      "description": "Can create and edit knowledge bases"
    },
    {
      "id": "7d6c5b4a-3f2e-1d0c-9b8a-7f6e5d4c3b2a",
      "name": "kb:delete",
      "description": "Can delete knowledge bases"
    }
  ]
}

Endpoint: PUT /api/roles/update Query Parameters:

Parameter	Required	Description
`org_id`	Yes	Organization ID
`role_id`	Yes	Role ID to update

Request Body: All fields are optional - only include fields you want to update:

Field	Type	Required	Description
`name`	string	No	New role name
`description`	string	No	New role description
`hierarchy_level`	integer	No	New hierarchy level
`permission_ids`	array	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.

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

import requests

url = "{{baseUrl}}/api/roles/remove"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
params = {
    "org_id": "your-org-id",
    "role_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
}

response = requests.delete(url, headers=headers, params=params)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/roles/remove";
const headers = {
    Authorization: "Bearer YOUR_TOKEN"
};
const params = {
    org_id: "your-org-id",
    role_id: "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
};

axios.delete(url, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

{
  "message": "Role deleted successfully"
}

Endpoint: DELETE /api/roles/remove Query Parameters:

Parameter	Required	Description
`org_id`	Yes	Organization ID
`role_id`	Yes	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).

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

import requests

url = "{{baseUrl}}/api/roles/list_roles"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
params = {
    "org_id": "your-org-id"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/roles/list_roles";
const headers = {
    Authorization: "Bearer YOUR_TOKEN"
};
const params = {
    org_id: "your-org-id"
};

axios.get(url, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

[
  {
    "id": "8c9d0e1f-2a3b-4c5d-6e7f-8g9h0i1j2k3l",
    "name": "owner",
    "description": "Organization owner with full access",
    "hierarchy_level": 100,
    "organization_id": null,
    "is_system_role": true,
    "created_at": "2023-07-01T00:00:00Z",
    "updated_at": "2023-07-01T00:00:00Z"
  },
  {
    "id": "9d0e1f2a-3b4c-5d6e-7f8g-9h0i1j2k3l4m",
    "name": "admin",
    "description": "Organization administrator",
    "hierarchy_level": 80,
    "organization_id": null,
    "is_system_role": true,
    "created_at": "2023-07-01T00:00:00Z",
    "updated_at": "2023-07-01T00:00:00Z"
  },
  {
    "id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
    "name": "Content Manager",
    "description": "Manages content and knowledge bases",
    "hierarchy_level": 40,
    "organization_id": "your-org-id",
    "is_system_role": false,
    "created_at": "2023-08-01T10:00:00Z",
    "updated_at": "2023-08-01T10:00:00Z"
  }
]

Endpoint: GET /api/roles/list_roles Query Parameters:

Parameter	Required	Description
`org_id`	Yes	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.

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

import requests

url = "{{baseUrl}}/api/roles/list_permissions"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/roles/list_permissions";
const headers = {
    Authorization: "Bearer YOUR_TOKEN"
};

axios.get(url, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "kb:read",
    "description": "Can view knowledge bases"
  },
  {
    "id": "8f7e6d5c-4b3a-2912-1098-7f6e5d4c3b2a",
    "name": "kb:write",
    "description": "Can create and edit knowledge bases"
  },
  {
    "id": "7d6c5b4a-3f2e-1d0c-9b8a-7f6e5d4c3b2a",
    "name": "kb:delete",
    "description": "Can delete knowledge bases"
  },
  {
    "id": "6c5b4a39-8d27-16f5-e4d3-c2b1a0f98e7d",
    "name": "conversation:read",
    "description": "Can view conversations"
  }
]

Endpoint: GET /api/roles/list_permissions

This returns all system-wide permissions. Use these permission IDs when creating or updating roles.

Create Permission

Create a new system-wide permission.

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"
  }'

import requests

url = "{{baseUrl}}/api/roles/permission"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "name": "reports:generate",
    "description": "Can generate reports"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/roles/permission";
const headers = {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
};
const data = {
    name: "reports:generate",
    description: "Can generate reports"
};

axios.post(url, data, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

{
  "id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
  "name": "reports:generate",
  "description": "Can generate reports"
}

Endpoint: POST /api/roles/permission Request Body:

Field	Type	Required	Description
`name`	string	Yes	Permission name (format: `resource:action`)
`description`	string	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"

import requests

url = "{{baseUrl}}/api/roles/permission"
headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}
params = {
    "permission_id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6"
}

response = requests.delete(url, headers=headers, params=params)
print(response.json())

const axios = require('axios');

const url = "{{baseUrl}}/api/roles/permission";
const headers = {
    Authorization: "Bearer YOUR_TOKEN"
};
const params = {
    permission_id: "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6"
};

axios.delete(url, { headers, params })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

Endpoint: DELETE /api/roles/permission Query Parameters:

Parameter	Required	Description
`permission_id`	Yes	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

Permission Format

Permissions follow the resource:action pattern:

Resources: kb, conversation, agent, tool, organization, users, roles
Actions: read, write, delete, admin, execute
Wildcards: *:read (read all resources), kb:* (all kb actions), *:* (full access)

Required Permissions

Create/Update/Delete Roles: Requires roles:write permission
Delete Roles: Requires roles:delete permission
View Roles: Requires roles:read permission
Manage Permissions: Requires system-level admin access

🎯 Welcome

🚀 Getting Started

💡 Core Concepts

🏗️ Platform Architecture

🔐 Security & Auth

📡 API Reference

🛠️ Development Guides

🚨 Troubleshooting

Authentication

Base URL

Endpoints Overview

Role Endpoints

Create Role

Update Role

Delete Role

List Roles

Permission Endpoints

List All Permissions

Create Permission

Delete Permission

Managing User Roles

Error Responses

Implementation Notes

System Roles

Custom Roles

Permission Format

Required Permissions

​Authentication

​Base URL

​Endpoints Overview

​Role Endpoints

​Create Role

​Update Role

​Delete Role

​List Roles

​Permission Endpoints

​List All Permissions

​Create Permission

​Delete Permission

​Managing User Roles

​Error Responses

​Implementation Notes

​System Roles

​Custom Roles

​Permission Format

​Required Permissions

Authentication

Base URL

Endpoints Overview

Role Endpoints

Create Role

Update Role

Delete Role

List Roles

Permission Endpoints

List All Permissions

Create Permission

Delete Permission

Managing User Roles

Error Responses

Implementation Notes

System Roles

Custom Roles

Permission Format

Required Permissions