Skip to main content

​
Overview

The Roles API provides endpoints to create, manage, and assign roles to users. Roles are used to group permissions and control access to different parts of the application.

​
Authentication

All Roles endpoints require the Administrator role. You must include a valid JWT token in the Authorization header: 
Authorization: Bearer <your-token>

​
Base URL

/api/Roles

​
Available Endpoints

​
Role Management

MethodEndpointDescription
GET/api/RolesGet all roles
GET/api/Roles/{roleId}Get a specific role by ID
POST/api/RolesCreate a new role
PUT/api/Roles/{roleId}Update an existing role
DELETE/api/Roles/{roleId}Delete a role

​
Role Assignment

MethodEndpointDescription
GET/api/Roles/user/{userId}Get all roles assigned to a user
POST/api/Roles/assignAssign a role to a user
POST/api/Roles/removeRemove a role from a user

​
Role Entity Structure

Roles in the system have the following structure:
​
id
string
required
Unique identifier for the role
​
name
string
required
Name of the role (e.g., “Administrator”, “User”, “Manager”)
​
normalizedName
string
Normalized version of the role name (uppercase)
​
permissionCount
integer
Number of permissions assigned to this role

​
Predefined Roles

The system includes the following predefined roles:
  • Administrator - Full system access
  • User - Standard user access
  • Manager - Management-level access

​
Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Administrator",
  "normalizedName": "ADMINISTRATOR",
  "permissionCount": 15
}

​
Error Responses

All endpoints may return the following error responses:
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication token
  • 403 Forbidden - User does not have Administrator role
  • 404 Not Found - Role not found
  • 500 Internal Server Error - Server error

​
Next Steps

Create Role

Learn how to create new roles

Assign Role

Assign roles to users

Build docs developers (and LLMs) love

Get started for freeTalk to us