This guide provides detailed information about managing user roles through our API. Roles define permissions and access levels for users within the system. For security, always validate role permissions before granting access.

📌 Endpoints Overview

  • GET /api/user-roles
    Retrieve all available roles
    ⚠️ Requires system_admin scope

  • POST /api/user-roles
    Create a new role
    ✅ Example payload: 

    {
  "name": "developer",
  "description": "API access with limited permissions",
  "permissions": ["read_data", "write_logs"]
}

  • PUT /api/user-roles/{id}
    Update an existing role
    🔄 Supported fields: name, description, permissions

  • DELETE /api/user-roles/{id}
    Remove a role
    ⚠️ Will cascade delete associated users

📊 Response Examples

Status Code Description Example Payload
200 OK Role details {"id": 1, "name": "admin"}
201 Created New role successfully {"message": "Role created", "role_id": 42}
204 No Content Role deleted -
400 Bad Request Invalid input {"error": "Missing required field 'name'"}

🔐 Role Permissions Matrix

  • admin
    🚀 Full access to all system features

    • Create users
    • Manage roles
    • View audit logs

  • editor
    ✏️ Limited editing capabilities

    • Update user profiles
    • Modify role permissions

  • viewer
    👁️ Read-only access

    • View user lists
    • Check role assignments
User Roles Overview

📚 Related Documentation

For deeper insights into role-based access control:
Learn about RBAC implementation
View role permission categories