Role Endpoints

The role management endpoints provide CRUD operations for roles and their associated permissions. All endpoints require ADMIN or PLATFORM_ADMIN privileges. Served by RoleController at /api/v1/roles.

Endpoints

POST /api/v1/roles

Creates a new role within the tenant.

Headers: X-Tenant-ID (required)

{
  "name": "DATA_ANALYST",
  "description": "Can view and query data assets",
  "permissionIds": [10, 11, 12]
}

RoleResponse Structure

{
  "id": 5,
  "name": "DATA_ANALYST",
  "description": "Can view and query data assets",
  "systemRole": false,
  "permissions": [
    { "id": 10, "name": "queries:read", "resource": "queries", "action": "read" },
    { "id": 11, "name": "queries:execute", "resource": "queries", "action": "execute" }
  ],
  "userCount": 12,
  "createdAt": "2026-01-15T10:00:00Z",
  "updatedAt": "2026-01-20T14:30:00Z"
}

Permission Management

Roles use a resource-action permission model. Permissions can be managed in three ways:

Replace all permissions (PUT /api/v1/roles/:roleId/permissions):

[10, 11, 12, 13]

Replaces the entire permission set with the provided IDs.

Add permissions (POST /api/v1/roles/:roleId/permissions):

[14, 15]

Adds the specified permission IDs to the existing set.

Remove permissions (DELETE /api/v1/roles/:roleId/permissions):

[12, 13]

Removes the specified permission IDs from the role.

System Roles

System roles (where systemRole is true) cannot be deleted or renamed. They include built-in roles such as ADMIN, PLATFORM_ADMIN, USER, and VIEWER. Their permissions can still be modified by administrators.