Appearance
Roles API
Base route: /api/roles
Auth required: ✅ JWT Bearer
GET /api/roles
Returns all roles (active and inactive).
Permission: None required (any authenticated user)
Response 200 OK
json
[
{
"id": 1,
"name": "Admin",
"description": "Full system access",
"isSystem": true,
"isActive": true,
"createdAt": "2026-01-01T00:00:00Z"
},
{
"id": 2,
"name": "Pharmacist",
"description": "Standard operator access",
"isSystem": true,
"isActive": true,
"createdAt": "2026-01-01T00:00:00Z"
}
]GET /api/roles/:id
Returns a single role by ID.
Response — Single 200 OK — RoleDto
Response — Not Found 404
POST /api/roles
Creates a new role.
Permission: Role:Create
INFO
isSystem is always set to false on created roles. System roles (Admin, Pharmacist) are created only via seed migrations and cannot be reproduced through the API.
Request Body
json
{
"name": "Auditor",
"description": "Read-only access to all modules"
}Response — Created 201 — RoleDto
Response — Invalid 400
PUT /api/roles/:id
Updates a role's name and description.
Permission: Role:Update
WARNING
Cannot change isSystem or isActive via this endpoint. To deactivate a non-system role use the DELETE endpoint.
Response — Updated 200 OK — Updated RoleDto
Response — Not Found 404
DELETE /api/roles/:id
Soft-deletes a role (sets isActive = false).
Permission: Role:Delete
DANGER
System roles (isSystem = true) cannot be deleted — returns 400 Bad Request.