Staff Management

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

Method	Route	Auth	Description
GET	`/web-app/staff`	🔐 JWT	List all school staff
POST	`/web-app/staff`	🔐 JWT	Register a new staff member
GET	`/web-app/staff/:id`	🔐 JWT	View single staff profile
PUT	`/web-app/staff/:id`	🔐 JWT	Update staff information
POST	`/web-app/staff/:id/assign-students`	🔐 JWT	Map students to a teacher
POST	`/web-app/staff/:id/unassign-students`	🔐 JWT	Remove students from teacher
POST	`/web-app/staff/:id/reset-pin`	🔐 JWT	Force reset staff PIN
POST	`/web-app/staff/:id/archive`	🔐 JWT	Archive 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:

Field	Type	Required	Description
skole_id	string	Yes	School identifier.
search	string	No	Search by name or phone.
status	string	No	Enum: `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:

Field	Type	Description
id	number	Unique 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:

Field	Type	Description
id	number	Staff 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 Code	Description
409	Staff member with this phone/email already exists
403	Forbidden: 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.

Modules

API

Data Schema

Changelog

1. API Purpose

2. Endpoint Definition

3. Authentication Flow

4. Request Structure

GET /web-app/staff

POST /web-app/staff

GET /web-app/staff/:id

PUT /web-app/staff/:id

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

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

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

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

5. Response Structure

Success: Staff List (200 OK)

Success: Staff Registered (201 Created)

Success: Staff Profile View (200 OK)

Success: Profile Updated (200 OK)

Success: Students Assigned (201 Created)

Success: Students Unassigned (201 Created)

Success: PIN Reset (201 Created)

Success: Record Archived (201 Created)

6. Error Responses

7. Security Considerations

8. Token Usage

9. Token Refresh

10. Logout / Session Invalidation

11. Usage Example (cURL)

12. Notes / Special Behaviors

​1. API Purpose

​2. Endpoint Definition

​3. Authentication Flow

​4. Request Structure

​GET /web-app/staff

​POST /web-app/staff

​GET /web-app/staff/:id

​PUT /web-app/staff/:id

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

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

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

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

​5. Response Structure

​Success: Staff List (200 OK)

​Success: Staff Registered (201 Created)

​Success: Staff Profile View (200 OK)

​Success: Profile Updated (200 OK)

​Success: Students Assigned (201 Created)

​Success: Students Unassigned (201 Created)

​Success: PIN Reset (201 Created)

​Success: Record Archived (201 Created)

​6. Error Responses

​7. Security Considerations

​8. Token Usage

​9. Token Refresh

​10. Logout / Session Invalidation

​11. Usage Example (cURL)

​12. Notes / Special Behaviors

1. API Purpose

2. Endpoint Definition

3. Authentication Flow

4. Request Structure

GET /web-app/staff

POST /web-app/staff

GET /web-app/staff/:id

PUT /web-app/staff/:id

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

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

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

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

5. Response Structure

Success: Staff List (200 OK)

Success: Staff Registered (201 Created)

Success: Staff Profile View (200 OK)

Success: Profile Updated (200 OK)

Success: Students Assigned (201 Created)

Success: Students Unassigned (201 Created)

Success: PIN Reset (201 Created)

Success: Record Archived (201 Created)

6. Error Responses

7. Security Considerations

8. Token Usage

9. Token Refresh

10. Logout / Session Invalidation

11. Usage Example (cURL)

12. Notes / Special Behaviors