Skip to content

Administration - Roles

Manage platform roles and permissions. Roles define sets of permission scopes that can be assigned to users within a tenant.

Base path: /api/v1/admin/roles

Method Endpoint Description
GET /api/v1/admin/roles List Roles
GET /api/v1/admin/roles/{roleId} Get Role

List Roles

GET /api/v1/admin/roles

Requires Authentication - Scopes: admin:roles:read

Retrieve a paginated list of roles for the current tenant. Supports filtering by role type and searching by name or slug.

Query Parameters
Parameter Type Required Default Description
page integer No 0 Page number (zero-based).
size integer No 20 Page size (max 100).
type string No - Filter by role type: system, custom.
search string No - Partial case-insensitive search on role name or slug.
sortBy string No hierarchyOrder Sort field: name, slug, hierarchyOrder, createdAt, updatedAt.
sortDir string No desc Sort direction: asc or desc. 
curl -X GET "https://koldan.dixilang.com/api/v1/admin/roles?type=custom&search=editor" \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

resp = requests.get(
    "https://koldan.dixilang.com/api/v1/admin/roles",
    headers={"Authorization": f"Bearer {JWT}"},
    params={"type": "custom", "search": "editor"}
)
print(resp.json())
RolePageResponse
Field Type Nullable Description
content RoleResponse[] No Array of role objects.
page integer No Current page number.
size integer No Number of items in this page.
totalElements long No Total number of matching roles.
RolePageResponse
{
  "content": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Tenant Admin",
      "slug": "tenant-admin",
      "description": "Full access to tenant resources",
      "type": "SYSTEM",
      "hierarchyOrder": 100,
      "scopes": ["admin:roles:read", "admin:users:read", "..."],
      "mutable": false,
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  ],
  "page": 0,
  "size": 1,
  "totalElements": 1
}
Status Description
200 OK Roles retrieved successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.

Get Role

GET /api/v1/admin/roles/{roleId}

Requires Authentication - Scopes: admin:roles:read

Retrieve detailed information for a single role by its unique identifier.

Path Parameters
Parameter Type Required Description
roleId string (UUID) Yes Unique identifier of the role. 
curl -X GET https://koldan.dixilang.com/api/v1/admin/roles/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: $KOLDAN_API_KEY"

import requests

role_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
resp = requests.get(
    f"https://koldan.dixilang.com/api/v1/admin/roles/{role_id}",
    headers={"Authorization": f"Bearer {JWT}"}
)
print(resp.json())
RoleResponse

Returns the role metadata object.

Status Description
200 OK Role details retrieved successfully.
401 Unauthorized Missing or invalid authentication.
403 Forbidden Insufficient scope.
404 Not Found Role not found.

Data Types

RoleResponse

Field Type Nullable Description
id string (UUID) No Unique identifier of the role.
name string No Human-readable role name.
slug string No URL-safe role identifier.
description string Yes Role description.
type string No Role type: SYSTEM or CUSTOM.
hierarchyOrder integer No Position in the role hierarchy (higher = more privileged).
scopes string[] No Permission scopes granted by this role.
mutable boolean No Whether the role can be modified or deleted.
createdAt string (ISO 8601) No Role creation timestamp.
updatedAt string (ISO 8601) No Role last update timestamp.

Enumerations

RoleType

Value Description
SYSTEM Pre-defined platform role. Cannot be modified or deleted.
CUSTOM User-defined role for specific tenant needs.

Role Hierarchy

Roles in Koldan are hierarchical. Users with higher-order roles can generally manage users with lower-order roles, depending on specific permission scopes. System roles are immutable and provided by the platform.

Permissions

Permissions are granted via scopes (e.g., speech:files:read). A role consolidates multiple scopes into a single assignable entity. To see a user's effective permissions, use the Roles and Permissions documentation.