Sessions & Diagnostics

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

Method	Route	Auth	Description
GET	`/parent-app/sessions`	🔐 JWT	List active parent mobile sessions
DELETE	`/parent-app/sessions/:id`	🔐 JWT	Remote logout a specific device
DELETE	`/parent-app/sessions`	🔐 JWT	Logout all except current
GET	`/web-app/sessions`	🔐 JWT	List active web admin sessions
DELETE	`/web-app/sessions/:id`	🔐 JWT	Terminate a web session
GET	`/web-app/diagnostics/health`	🔐 JWT	Admin: Check school system health
POST	`/web-app/diagnostics/test-push`	🔐 JWT	Admin: 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:

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

Field	Type	Description
id	number	Web 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 Code	Description
403	Forbidden: Attempting to delete a session belonging to another user
404	Session 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.

Modules

API

Data Schema

Changelog

1. API Purpose

2. Endpoint Definition

3. Authentication Flow

4. Request Structure

GET /parent-app/sessions

DELETE /parent-app/sessions/:id

DELETE /parent-app/sessions

GET /web-app/sessions

DELETE /web-app/sessions/:id

GET /web-app/diagnostics/health

POST /web-app/diagnostics/test-push

5. Response Structure

Success: Session List (200 OK)

Success: Session Terminated (200 OK)

Success: Bulk Logout (200 OK)

Success: System Health (200 OK)

Success: Test Push Sent (200 OK)

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 /parent-app/sessions

​DELETE /parent-app/sessions/:id

​DELETE /parent-app/sessions

​GET /web-app/sessions

​DELETE /web-app/sessions/:id

​GET /web-app/diagnostics/health

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

​5. Response Structure

​Success: Session List (200 OK)

​Success: Session Terminated (200 OK)

​Success: Bulk Logout (200 OK)

​Success: System Health (200 OK)

​Success: Test Push Sent (200 OK)

​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 /parent-app/sessions

DELETE /parent-app/sessions/:id

DELETE /parent-app/sessions

GET /web-app/sessions

DELETE /web-app/sessions/:id

GET /web-app/diagnostics/health

POST /web-app/diagnostics/test-push

5. Response Structure

Success: Session List (200 OK)

Success: Session Terminated (200 OK)

Success: Bulk Logout (200 OK)

Success: System Health (200 OK)

Success: Test Push Sent (200 OK)

6. Error Responses

7. Security Considerations

8. Token Usage

9. Token Refresh

10. Logout / Session Invalidation

11. Usage Example (cURL)

12. Notes / Special Behaviors