Role Assignment

Role assignment controls which roles are associated with a user. Roles determine the user's permissions across the platform. The endpoint replaces all existing role assignments with the provided set of role IDs.

curl -X PUT http://localhost:8081/api/v1/users/42/roles \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '[1, 3, 5]'

Request Body

A JSON array of role IDs (Long values). This replaces all existing role assignments.

Response (200 OK)

Returns the updated UserResponse with the new role assignments.

{
  "id": 42,
  "email": "user@company.com",
  "roles": [
    { "id": 1, "name": "user" },
    { "id": 3, "name": "analyst" },
    { "id": 5, "name": "admin" }
  ]
}

Important Behaviors

• Replace semantics: The request replaces all existing roles. To add a role, include all current role IDs plus the new one.
• Permission cache invalidation: When roles change, the PermissionCacheService is notified to invalidate the user's cached permissions.
• Requires ADMIN or PLATFORM_ADMIN role: Protected by @PreAuthorize("hasAnyRole('ADMIN', 'PLATFORM_ADMIN')").
• Tenant-scoped: Only roles belonging to the same tenant can be assigned.

Error Codes