> ## Documentation Index
> Fetch the complete documentation index at: https://docs.criar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions & Diagnostics

> Device session management, multi-device invalidation, and internal school/system health 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:**

```http theme={null}
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:**

```http theme={null}
Authorization: Bearer <TOKEN>
```

#### GET /web-app/sessions

**Headers:**

```http theme={null}
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:**

```http theme={null}
Authorization: Bearer <TOKEN>
```

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

**Request Body:**

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "success": true,
  "message": "Remote session invalidated"
}
```

#### Success: Bulk Logout (200 OK)

**Route:** `DELETE /parent-app/sessions`

```json theme={null}
{
  "success": true,
  "message": "All other sessions have been logged out"
}
```

#### Success: System Health (200 OK)

**Route:** `GET /web-app/diagnostics/health`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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

```http theme={null}
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)

```bash theme={null}
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.