List Roles
Get all available roles in the system.
curl -X GET https://your-api.com/api/roles \
-H "Authorization: Bearer YOUR_TOKEN"
Response
Array of role objects sorted by name
{
"success": true,
"roles": [
{
"role_id": 1,
"role_key": "admin",
"role_name": "Administrator",
"description": "Full system access",
"created_by": 1,
"created_at": "2025-01-01T00:00:00Z"
},
{
"role_id": 2,
"role_key": "technician",
"role_name": "Technician",
"description": "Field service technician",
"created_by": 1,
"created_at": "2025-01-01T00:00:00Z"
}
]
}
Create Role
Create a new role with custom permissions.
curl -X POST https://your-api.com/api/roles \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"role_key": "supervisor",
"role_name": "Supervisor",
"description": "Team supervisor with limited admin access"
}'
Request Body
Unique role identifier (lowercase, no spaces)
Response
{
"success": true,
"role": {
"role_id": 5,
"role_key": "supervisor",
"role_name": "Supervisor",
"description": "Team supervisor with limited admin access",
"created_by": 1,
"created_at": "2026-03-03T11:15:00Z"
}
}
Error Response
Missing Required Fields (400)
{
"success": false,
"error": "role_key and role_name required"
}
Assign User to Role
Assign a specific user to a role.
curl -X POST https://your-api.com/api/roles/2/users/15 \
-H "Authorization: Bearer YOUR_TOKEN"
Path Parameters
Response
{
"success": true,
"assigned": {
"user_id": 15,
"role_id": 2,
"assigned_at": "2026-03-03T11:20:00Z"
}
}
If the user is already assigned to the role, the operation completes successfully but returns assigned: null due to the ON CONFLICT DO NOTHING constraint.
Remove User from Role
Remove a user’s role assignment.
curl -X DELETE https://your-api.com/api/roles/2/users/15 \
-H "Authorization: Bearer YOUR_TOKEN"
Path Parameters
Response
{
"success": true,
"removed": true
}
List Users in Role
Get all users assigned to a specific role.
curl -X GET https://your-api.com/api/roles/2/users \
-H "Authorization: Bearer YOUR_TOKEN"
Path Parameters
Response
{
"success": true,
"users": [
{
"user_id": 15,
"email": "[email protected]",
"first_name": "John",
"last_name": "Smith"
},
{
"user_id": 23,
"email": "[email protected]",
"first_name": "Mary",
"last_name": "Johnson"
}
]
}
Get Role Permissions
Get all module permissions for a role.
curl -X GET https://your-api.com/api/roles/2/permissions \
-H "Authorization: Bearer YOUR_TOKEN"
Path Parameters
Response
Array of module permission objectspermissions[].module_name
Module name
permissions[].module_path
Route path for the module
View permission (null if not assigned)
Whether access is blocked (null if not assigned)
permissions[].has_permission
Whether the role has this permission assigned
{
"success": true,
"permissions": [
{
"module_id": 1,
"module_name": "Dashboard",
"module_path": "/dashboard",
"module_description": "Main dashboard",
"can_view": true,
"is_blocked": false,
"role_module_permission_id": 45,
"has_permission": true
},
{
"module_id": 10,
"module_name": "User Management",
"module_path": "/admin/users",
"module_description": "Manage system users",
"can_view": null,
"is_blocked": null,
"role_module_permission_id": null,
"has_permission": false
}
]
}
Update Role Permissions (Bulk)
Update multiple module permissions for a role in a single request.
curl -X PUT https://your-api.com/api/roles/2/permissions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{
"permissions": [
{
"module_id": 1,
"enabled": true,
"can_view": true,
"is_blocked": false
},
{
"module_id": 2,
"enabled": true,
"can_view": true,
"is_blocked": false
},
{
"module_id": 10,
"enabled": false
}
]
}'
Path Parameters
Request Body
Array of permission configurationsWhether to enable this permission (false will delete it)
View permission (required if enabled is true)
Response
This operation runs in a transaction. If any permission update fails, all changes are rolled back.
Permission Logic
- If
enabled: false, the permission is deleted from the database
- If
enabled: true, the permission is deleted and recreated with new values
- This ensures clean state without orphaned permissions
Delete Role Permission
Remove a specific module permission from a role.
curl -X DELETE https://your-api.com/api/roles/2/permissions/10 \
-H "Authorization: Bearer YOUR_TOKEN"
Path Parameters
Response
{
"success": true,
"removed": true
}