Roles API

The Roles module manages role-based access control (RBAC) for the system.

Model

{
  "id": "uuid",
  "name": "Teacher",
  "description": "Teacher role with classroom permissions",
  "code": "TEACHER",
  "permissions": {
    "Student": ["list", "read"],
    "Attendance": ["list", "read", "create", "update"],
    "Class": ["list", "read"]
  },
  "team_id": "team-uuid",
  "created_at": "2024-01-01T00:00:00Z"
}

Permissions Structure

Permissions are organized by module and action:

{
  "ModuleName": ["action1", "action2"]
}

Available Actions

Action	Description
`list`	View list of records
`read`	View single record details
`create`	Create new records
`update`	Modify existing records
`delete`	Delete records
`export`	Export records to Excel
`import`	Import records from Excel

Endpoints

List Roles

Endpoint: POST /api/roles/list

!!! warning “Admin Only” Role management requires admin role.

Get Role by ID

Endpoint: GET /api/roles/:id

Create Role

Endpoint: POST /api/roles

Request:

{
  "name": "Counselor",
  "description": "School counselor role",
  "code": "COUNSELOR",
  "permissions": {
    "Student": ["list", "read"],
    "Behavior": ["list", "read", "create", "update"],
    "Guardian": ["list", "read"]
  }
}

Update Role

Endpoint: PUT /api/roles/:id

Delete Role

Endpoint: DELETE /api/roles/:id

Save Permissions

Update role permissions:

Endpoint: PUT /api/roles/:id/save_permission

Request:

{
  "permissions": {
    "Student": ["list", "read", "create"],
    "Attendance": ["list", "read", "create", "update", "delete"]
  }
}

User-Role Assignment

Assign Users to Role

Endpoint: PUT /api/roles/:id/assign

Request:

{
  "user_ids": ["user-uuid-1", "user-uuid-2"]
}

Remove Users from Role

Endpoint: PUT /api/roles/:id/remove

Request:

{
  "user_ids": ["user-uuid-1"]
}

Built-in Roles

Role	Description
`Root`	Super admin with all permissions
`Admin`	Administrative staff
`Teacher`	Teaching staff
`Student`	Student (limited access)
`Guardian`	Parent/guardian (limited access)

Permission Check

The system checks permissions via middleware:

middlewares.PermissionMiddleware("Student", "create", "")

Returns 403 Forbidden if user lacks required permission.