> ## 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.

# Skole API — Overview & Authentication

> Global API conventions and the complete Authentication specification for Parent, Teacher, and Web Admin modules.

Welcome to the Skole API Reference. This documentation provides a comprehensive guide to the endpoints powering the Skole platform, following a strict 12-section professional standard for every module.

## Global Conventions

<info>
  * **Parent App (Mobile):** `/parent-app`
  * **Teachers App (Mobile):** `/teachers-app`
  * **Web Admin App:** `/web-app`
</info>

### Authentication Strategy

All endpoints (unless marked **Public**) require a valid JSON Web Token (JWT). The token can be provided via the `Authorization: Bearer` header, the `access_token` query parameter, or a cookie.

### Multi-Tenancy

Most requests in the Teacher and Web modules require a `skole_id` (School Identifier) to ensure data isolation.

***

## Authentication API Documentation (Complete Specification)

### 1. API Purpose

The Authentication module provides the secure entry point for all users of the Skole platform. It validates identities against role-specific data stores and issues JWT tokens that encapsulate user permissions and school context.

**Capabilities:**

* Single-page login for Parents and Staff using Phone + PIN.
* Email/Password authentication for Web Administrators.
* Secure session creation and device registration for push notifications.
* Remote session invalidation and multi-device support.

***

### 2. Endpoint Definition

| Property       | Value                                      |
| -------------- | ------------------------------------------ |
| Endpoint Group | Authentication Services                    |
| HTTP Methods   | POST, PUT, PATCH                           |
| Base Paths     | `/parent-app`, `/teachers-app`, `/web-app` |
| Primary Tech   | NestJS + JWT + Prisma                      |

#### Core Auth Endpoints

| Method | Route                                     | Auth      | Description                       |
| ------ | ----------------------------------------- | --------- | --------------------------------- |
| POST   | `/parent-app/parent-auth-verification`    | 🔓 Public | Parent login (Phone/Email + PIN)  |
| POST   | `/teachers-app/teacher-auth-verification` | 🔓 Public | Teacher/Staff login (Phone + PIN) |
| POST   | `/web-app/signin`                         | 🔓 Public | Admin login (Email + Password)    |
| POST   | `/web-app/signup`                         | 🔓 Public | Admin registration                |
| POST   | `/web-app/logout`                         | 🔐 JWT    | Invalidate current session        |

***

### 3. Authentication Flow

1. **Submission:** Client sends credentials (e.g., Phone + PIN) to the appropriate module endpoint.
2. **Identification:** System queries role-specific tables (`parent_details`, `staff`, or `users`).
3. **Validation:** System performs PIN/Password verification via `bcrypt`.
4. **Session Creation:** A unique `session_token` is generated and stored in a sessions table (`parent_devices`, `staff_sessions`, or `user_sessions`).
5. **JWT Issuance:** System signs a JWT containing `sub` (user\_id), `skole_id`, `type`, and the `session_token`.
6. **Interaction:** Client stores the token and includes it in the `Authorization` header for all subsequent requests.

***

### 4. Request Structure

#### POST /parent-app/parent-auth-verification

**Request Body:**

```json theme={null}
{
  "phone_no": "9876543210",
  "pin": "1234",
  "fcm_token": "fcm_token_xyz"
}
```

#### POST /teachers-app/teacher-auth-verification

**Request Body:**

```json theme={null}
{
  "phone_no": "9000012345",
  "pin": "5678",
  "skole_id": "SKL001"
}
```

#### POST /web-app/signin

**Request Body:**

```json theme={null}
{
  "email": "admin@skole.com",
  "password": "SecurePassword123"
}
```

#### POST /web-app/signup

**Request Body:**

```json theme={null}
{
  "name": "Admin User",
  "email": "admin@skole.com",
  "password": "SecurePassword123",
  "skole_id": "SKL001"
}
```

***

### 5. Response Structure

#### Success: Parent Login (200 OK)

**Route:** `/parent-app/parent-auth-verification`

```json theme={null}
{
  "success": true,
  "message": "Authentication successful",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "parent": {
      "id": 123,
      "father_name": "Rajesh Kumar",
      "skole_id": "SKL001"
    },
    "children": [
      { "id": 45, "name": "Aarav", "roll_no": "A001" }
    ]
  }
}
```

#### Success: Teacher Login (200 OK)

**Route:** `/teachers-app/teacher-auth-verification`

```json theme={null}
{
  "success": true,
  "message": "Access granted",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "staff": {
      "id": 10,
      "name": "Sarah Miller",
      "designation": "Class Teacher",
      "skole_id": "SKL001"
    }
  }
}
```

#### Success: Admin Signin (200 OK)

**Route:** `/web-app/signin`

```json theme={null}
{
  "success": true,
  "message": "Welcome back, Admin",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "name": "Super Admin",
      "email": "admin@skole.com"
    }
  }
}
```

#### Success: Admin Signup (201 Created)

**Route:** `/web-app/signup`

```json theme={null}
{
  "success": true,
  "message": "Account created successfully",
  "data": {
    "user_id": 2,
    "skole_id": "SKL001"
  }
}
```

#### Success: Logout (200 OK)

**Route:** `/{module}/logout`

```json theme={null}
{
  "success": true,
  "message": "Logged out successfully"
}
```

***

### 6. Error Responses

| HTTP Code | Error Code    | Description                               |
| --------- | ------------- | ----------------------------------------- |
| 401       | UNAUTHORIZED  | Invalid phone number or PIN               |
| 403       | FORBIDDEN     | Account disabled or school access revoked |
| 400       | BAD\_REQUEST  | Missing required fields (e.g., skole\_id) |
| 500       | SERVER\_ERROR | Internal database or JWT signing error    |

***

### 7. Security Considerations

* **PIN Security:** PINs are never stored in plain text; they are hashed using `bcrypt` with a salt factor of 10.
* **Token Expiry:** Mobile sessions are long-lived (30 days) but can be revoked remotely via the Sessions API.
* **Tenant Isolation:** The `skole_id` is embedded in the JWT and enforced by a global `SkoleGuard` to prevent cross-school data leaks.

***

### 8. Token Usage

Users must include the token in the `Authorization` header:

```http theme={null}
GET /parent-app/student-detail
Authorization: Bearer <JWT_TOKEN>
```

***

### 9. Token Refresh

Token rotation is handled during the login phase. If a token is near expiry, the client should perform a silent re-authentication or use the specific refresh flow (where available).

***

### 10. Logout / Session Invalidation

**Endpoint:** `POST /{module}/logout`

This endpoint marks the `session_token` as inactive in the database. Even if the JWT has not expired, the API will reject any request containing an invalidated session token.

***

### 11. Usage Example (cURL)

```bash theme={null}
curl -X POST http://localhost:3000/parent-app/parent-auth-verification \
-H "Content-Type: application/json" \
-d '{
  "phone_no": "9876543210",
  "pin": "1234"
}'
```

***

### 12. Notes / Special Behaviors

* **Sibling Logic:** If a parent has multiple children in the same school, the auth response returns a consolidated list of all children linked to that phone number/PIN.
* **FCM Registration:** The `fcm_token` provided during login is automatically linked to the session, enabling real-time push notifications for that specific device.