> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zyeta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles Service API

> API reference for managing roles and permissions

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.

<CodeGroup>
  ```bash Request theme={null}
  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"
      ]
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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));
  ```

  ```json Response theme={null}
  {
    "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"
      }
    ]
  }
  ```
</CodeGroup>

**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           |

<Note>
  Requires `roles:write` permission. System roles (owner, admin, member, guest) cannot be created this way - they are automatically created with each organization.
</Note>

### Update Role

Update an existing custom role.

<CodeGroup>
  ```bash Request theme={null}
  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"
      ]
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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));
  ```

  ```json Response theme={null}
  {
    "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"
      }
    ]
  }
  ```
</CodeGroup>

**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) |

<Warning>
  System roles (owner, admin, member, guest) cannot be updated. Only custom roles created via the API can be modified.
</Warning>

### Delete Role

Delete a custom role from an organization.

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

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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));
  ```

  ```json Response theme={null}
  {
    "message": "Role deleted successfully"
  }
  ```
</CodeGroup>

**Endpoint:** `DELETE /api/roles/remove`

**Query Parameters:**

| Parameter | Required | Description       |
| --------- | -------- | ----------------- |
| `org_id`  | Yes      | Organization ID   |
| `role_id` | Yes      | Role ID to delete |

<Warning>
  * System roles cannot be deleted
  * Roles assigned to members cannot be deleted (reassign members first)
  * This action cannot be undone
</Warning>

### List Roles

Retrieve all roles for an organization (includes both system roles and custom roles).

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "{{baseUrl}}/api/roles/list_roles?org_id=your-org-id" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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));
  ```

  ```json Response theme={null}
  [
    {
      "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"
    }
  ]
  ```
</CodeGroup>

**Endpoint:** `GET /api/roles/list_roles`

**Query Parameters:**

| Parameter | Required | Description     |
| --------- | -------- | --------------- |
| `org_id`  | Yes      | Organization ID |

<Note>
  Returns both system roles (owner, admin, member, guest) and organization-specific custom roles. System roles have `is_system_role: true` and `organization_id: null`.
</Note>

## Permission Endpoints

### List All Permissions

Retrieve all available permissions in the system.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "{{baseUrl}}/api/roles/list_permissions" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  import requests

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

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

  ```javascript JavaScript theme={null}
  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));
  ```

  ```json Response theme={null}
  [
    {
      "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"
    }
  ]
  ```
</CodeGroup>

**Endpoint:** `GET /api/roles/list_permissions`

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

### Create Permission

Create a new system-wide permission.

<CodeGroup>
  ```bash Request theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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));
  ```

  ```json Response theme={null}
  {
    "id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6",
    "name": "reports:generate",
    "description": "Can generate reports"
  }
  ```
</CodeGroup>

**Endpoint:** `POST /api/roles/permission`

**Request Body:**

| Field         | Type   | Required | Description                                 |
| ------------- | ------ | -------- | ------------------------------------------- |
| `name`        | string | Yes      | Permission name (format: `resource:action`) |
| `description` | string | No       | Permission description                      |

<Note>
  Permissions follow the `resource:action` naming convention (e.g., `kb:read`, `agent:execute`, `*:admin`).
</Note>

### Delete Permission

Delete a permission from the system.

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE "{{baseUrl}}/api/roles/permission?permission_id=a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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));
  ```
</CodeGroup>

**Endpoint:** `DELETE /api/roles/permission`

**Query Parameters:**

| Parameter       | Required | Description             |
| --------------- | -------- | ----------------------- |
| `permission_id` | Yes      | Permission ID to delete |

<Warning>
  Deleting a permission will remove it from all roles that have it assigned. This action cannot be undone.
</Warning>

## 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