Skip to main content

​
1. API Purpose

The Sessions API provides users with control over their active logins. It allows parents and staff to view where they are logged in and remotely terminate unauthorized sessions. The Diagnostics layer provides school administrators with tools to verify system health and notification delivery status.

​
2. Endpoint Definition

MethodRouteAuthDescription
GET/parent-app/sessions🔐 JWTList active parent mobile sessions
DELETE/parent-app/sessions/:id🔐 JWTRemote logout a specific device
DELETE/parent-app/sessions🔐 JWTLogout all except current
GET/web-app/sessions🔐 JWTList active web admin sessions
DELETE/web-app/sessions/:id🔐 JWTTerminate a web session
GET/web-app/diagnostics/health🔐 JWTAdmin: Check school system health
POST/web-app/diagnostics/test-push🔐 JWTAdmin: Diagnostic push notification test

​
3. Authentication Flow

Standard JWT validation.
  • Sessions: Users can only view or delete sessions belonging to their own ID.
  • Diagnostics: Restricted to Super Admins and School IT contacts.

​
4. Request Structure

​
GET /parent-app/sessions

Headers: 
Authorization: Bearer <JWT_TOKEN>

​
DELETE /parent-app/sessions/:id

URL Parameters:
FieldTypeDescription
idnumberID of the session to terminate.

​
DELETE /parent-app/sessions

Description: Terminates all sessions except the current one. Headers: 
Authorization: Bearer <TOKEN>

​
GET /web-app/sessions

Headers: 
Authorization: Bearer <ADMIN_TOKEN>

​
DELETE /web-app/sessions/:id

URL Parameters:
FieldTypeDescription
idnumberWeb session ID to terminate.

​
GET /web-app/diagnostics/health

Headers: 
Authorization: Bearer <TOKEN>

​
POST /web-app/diagnostics/test-push

Request Body: 
{
  "skole_id": "SKL001",
  "target_user_id": 1,
  "target_role": "parent",
  "message": "Diagnostic Test"
}

​
5. Response Structure

​
Success: Session List (200 OK)

Route: GET /{module}/sessions 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "device_name": "iPhone 15 Pro",
      "last_active": "2024-03-16T14:00:00Z",
      "is_current": true
    },
    {
      "id": 2,
      "device_name": "Samsung S24",
      "last_active": "2024-03-15T10:00:00Z",
      "is_current": false
    }
  ]
}

​
Success: Session Terminated (200 OK)

Route: DELETE /{module}/sessions/:id 
{
  "success": true,
  "message": "Remote session invalidated"
}

​
Success: Bulk Logout (200 OK)

Route: DELETE /parent-app/sessions 
{
  "success": true,
  "message": "All other sessions have been logged out"
}

​
Success: System Health (200 OK)

Route: GET /web-app/diagnostics/health 
{
  "success": true,
  "data": {
    "status": "operational",
    "uptime": "15 days",
    "services": { "database": "up", "redis": "up" }
  }
}

​
Success: Test Push Sent (200 OK)

Route: POST /web-app/diagnostics/test-push 
{
  "success": true,
  "message": "Diagnostic push notification delivered to provider"
}

​
6. Error Responses

HTTP CodeDescription
403Forbidden: Attempting to delete a session belonging to another user
404Session record not found

​
7. Security Considerations

  • Remote Revocation: When a session is deleted, any JWT associated with that session_token will be rejected by the API middleware on its next call.
  • Hardware IDs: Sessions are often linked to hardware identifiers to distinguish between multiple devices owned by the same user.

​
8. Token Usage

GET /parent-app/sessions
Authorization: Bearer <TOKEN>

​
9. Token Refresh

N/A.

​
10. Logout / Session Invalidation

This module is the core of session invalidation. Standard /logout calls the internal logic of this module to mark the current session as inactive.

​
11. Usage Example (cURL)

curl -X DELETE http://localhost:3000/parent-app/sessions/401 \
-H "Authorization: Bearer <TOKEN>"

​
12. Notes / Special Behaviors

  • Session Cleanup: The system periodically runs a background worker to prune expired sessions (e.g., sessions inactive for more than 90 days).
  • Diagnostics: Test-push diagnostics bypass standard filtering to ensure the delivery pipeline is functional.