Role Management

Production - RoleController - 8 endpoints at /api/v1/roles

Role management allows administrators to create, update, list, and delete roles within their tenant. All role endpoints require ADMIN or PLATFORM_ADMIN role.

6.5.1Role Endpoints

Create Role

curl -X POST http://localhost:8081/api/v1/roles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "data-analyst",
    "description": "Can read and query data, create dashboards"
  }'

Response (201 Created)

{
  "id": 10,
  "tenantId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "data-analyst",
  "description": "Can read and query data, create dashboards",
  "system": false,
  "permissions": [],
  "userCount": 0,
  "createdAt": "2026-02-12T10:00:00Z"
}

List Roles (Paginated)

curl -X GET "http://localhost:8081/api/v1/roles?page=0&size=20" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

List All Roles (No Pagination)

curl -X GET http://localhost:8081/api/v1/roles/all \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

Update Role

curl -X PUT http://localhost:8081/api/v1/roles/10 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "senior-data-analyst",
    "description": "Senior analyst with extended query permissions"
  }'

Manage Permissions

# Replace all permissions
curl -X PUT http://localhost:8081/api/v1/roles/10/permissions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '[1, 5, 8, 12]'
 
# Add permissions
curl -X POST http://localhost:8081/api/v1/roles/10/permissions \
  -d '[15, 16]'
 
# Remove permissions
curl -X DELETE http://localhost:8081/api/v1/roles/10/permissions \
  -d '[8]'

Delete Role

curl -X DELETE http://localhost:8081/api/v1/roles/10 \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

System roles (where system = true) cannot be deleted.

Role Inheritance

Roles support parent-child relationships. A child role inherits all permissions from its parent:

public Set<Permission> getAllPermissions() {
    Set<Permission> allPermissions = new HashSet<>(permissions);
    if (parentRole != null) {
        allPermissions.addAll(parentRole.getAllPermissions());
    }
    return allPermissions;
}

Error Codes

Code	HTTP Status	Description
`RESOURCE_NOT_FOUND`	404	Role not found
`RESOURCE_DUPLICATE`	409	Role name already exists in tenant
`BUSINESS_RULE_VIOLATION`	400	Cannot modify system role
`ACCESS_DENIED`	403	Not ADMIN or PLATFORM_ADMIN

Overview Permission Model