Skip to main content

​
1. API Purpose

The Staff Management API allows school administrators to manage their team. It defines designations with specific permissions that gate access to features within the Teacher App.

​
2. Endpoint Definition

MethodRouteAuthDescription
GET/web-app/staff🔐 JWTList all school staff
POST/web-app/staff🔐 JWTRegister a new staff member
GET/web-app/staff/:id🔐 JWTView single staff profile
PUT/web-app/staff/:id🔐 JWTUpdate staff information
POST/web-app/staff/:id/assign-students🔐 JWTMap students to a teacher
POST/web-app/staff/:id/unassign-students🔐 JWTRemove students from teacher
POST/web-app/staff/:id/reset-pin🔐 JWTForce reset staff PIN
POST/web-app/staff/:id/archive🔐 JWTArchive staff member record

​
3. Authentication Flow

Standard JWT validation.
  • Only users with Admin roles can access these endpoints.
  • Staff members can view their own profile data via the Auth response or the Profile API.

​
4. Request Structure

​
GET /web-app/staff

Query Parameters:
FieldTypeRequiredDescription
skole_idstringYesSchool identifier.
searchstringNoSearch by name or phone.
statusstringNoEnum: active, archived, all.

​
POST /web-app/staff

Request Body: 
{
  "name": "Sarah Miller",
  "designation": "Class Teacher",
  "phone_no": "9876543210",
  "email": "sarah.m@skole.com",
  "rbac": { "attendance": "manage", "diary": "manage" },
  "addresses": [
    {
      "address_type": "current",
      "address": "123 School Lane",
      "city": "Springfield",
      "pincode": 627001
    }
  ]
}

​
GET /web-app/staff/:id

URL Parameters:
FieldTypeDescription
idnumberUnique staff database ID.

​
PUT /web-app/staff/:id

Request Body: 
{
  "designation": "Senior Teacher",
  "email": "sarah.miller@skole.com"
}

​
POST /web-app/staff/:id/assign-students

Request Body: 
{
  "student_ids": [45, 46, 47]
}

​
POST /web-app/staff/:id/unassign-students

Request Body: 
{
  "student_ids": [45]
}

​
POST /web-app/staff/:id/reset-pin

Request Body: 
{
  "pin": "1234"
}

​
POST /web-app/staff/:id/archive

URL Parameters:
FieldTypeDescription
idnumberStaff ID to archive/toggle.

​
5. Response Structure

​
Success: Staff List (200 OK)

Route: GET /web-app/staff 
{
  "success": true,
  "data": [
    {
      "id": 10,
      "name": "Sarah Miller",
      "designation": "Class Teacher",
      "status": "active"
    }
  ]
}

​
Success: Staff Registered (201 Created)

Route: POST /web-app/staff 
{
  "success": true,
  "message": "Staff member registered successfully",
  "data": { "id": 11 }
}

​
Success: Staff Profile View (200 OK)

Route: GET /web-app/staff/:id 
{
  "success": true,
  "data": {
    "id": 10,
    "name": "Sarah Miller",
    "designation": "Class Teacher",
    "phone_no": "9876543210"
  }
}

​
Success: Profile Updated (200 OK)

Route: PUT /web-app/staff/:id 
{
  "success": true,
  "message": "Staff profile updated"
}

​
Success: Students Assigned (201 Created)

Route: POST /web-app/staff/:id/assign-students 
{
  "success": true,
  "message": "Students successfully mapped to teacher"
}

​
Success: Students Unassigned (201 Created)

Route: POST /web-app/staff/:id/unassign-students 
{
  "success": true,
  "message": "Students unmapped from teacher"
}

​
Success: PIN Reset (201 Created)

Route: POST /web-app/staff/:id/reset-pin 
{
  "success": true,
  "message": "Staff login PIN forced reset"
}

​
Success: Record Archived (201 Created)

Route: POST /web-app/staff/:id/archive 
{
  "success": true,
  "message": "Staff record archived"
}

​
6. Error Responses

HTTP CodeDescription
409Staff member with this phone/email already exists
403Forbidden: Only Super Admins can manage designations

​
7. Security Considerations

  • Encryption: Staff PINs are hashed using bcrypt.
  • RBAC Enforcement: The Teacher App reads the RBAC JSON on login to dynamically enable/disable menu items and UI controls.

​
8. Token Usage

GET /web-app/staff
Authorization: Bearer <ADMIN_TOKEN>

​
9. Token Refresh

N/A.

​
10. Logout / Session Invalidation

N/A.

​
11. Usage Example (cURL)

curl -X POST http://localhost:3000/web-app/staff/1/assign-students \
-H "Authorization: Bearer <TOKEN>" \
-d '{"student_ids": [45, 46]}'

​
12. Notes / Special Behaviors

  • Status Toggle: Setting a staff member’s status to 0 immediately revokes their Teacher App access, even if their token hasn’t expired (checked via session middleware).
  • Multi-School Staff: A staff member can theoretically belong to multiple schools, but their session is always scoped to a single skole_id.