Skole API — Overview & Authentication

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

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

Submission: Client sends credentials (e.g., Phone + PIN) to the appropriate module endpoint.
Identification: System queries role-specific tables (parent_details, staff, or users).
Validation: System performs PIN/Password verification via bcrypt.
Session Creation: A unique session_token is generated and stored in a sessions table (parent_devices, staff_sessions, or user_sessions).
JWT Issuance: System signs a JWT containing sub (user_id), skole_id, type, and the session_token.
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:

{
  "phone_no": "9876543210",
  "pin": "1234",
  "fcm_token": "fcm_token_xyz"
}

POST /teachers-app/teacher-auth-verification

Request Body:

{
  "phone_no": "9000012345",
  "pin": "5678",
  "skole_id": "SKL001"
}

Request Body:

{
  "email": "admin@skole.com",
  "password": "SecurePassword123"
}

Request Body:

{
  "name": "Admin User",
  "email": "admin@skole.com",
  "password": "SecurePassword123",
  "skole_id": "SKL001"
}

5. Response Structure

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

{
  "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" }
    ]
  }
}

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

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

Route: /web-app/signin

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

Route: /web-app/signup

{
  "success": true,
  "message": "Account created successfully",
  "data": {
    "user_id": 2,
    "skole_id": "SKL001"
  }
}

Success: Logout (200 OK)

Route: /{module}/logout

{
  "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:

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)

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.

Modules

API

Data Schema

Changelog

Skole API — Overview & Authentication

Global Conventions

Authentication Strategy

Multi-Tenancy

Authentication API Documentation (Complete Specification)

1. API Purpose

2. Endpoint Definition

Core Auth Endpoints

3. Authentication Flow

4. Request Structure

POST /parent-app/parent-auth-verification

POST /teachers-app/teacher-auth-verification

5. Response Structure

Success: Logout (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

​Global Conventions

​Authentication Strategy

​Multi-Tenancy

​Authentication API Documentation (Complete Specification)

​1. API Purpose

​2. Endpoint Definition

​Core Auth Endpoints

​3. Authentication Flow

​4. Request Structure

​POST /parent-app/parent-auth-verification

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

​POST /web-app/signin

​POST /web-app/signup

​5. Response Structure

​Success: Parent Login (200 OK)

​Success: Teacher Login (200 OK)

​Success: Admin Signin (200 OK)

​Success: Admin Signup (201 Created)

​Success: Logout (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

Global Conventions

Authentication Strategy

Multi-Tenancy

Authentication API Documentation (Complete Specification)

1. API Purpose

2. Endpoint Definition

Core Auth Endpoints

3. Authentication Flow

4. Request Structure

POST /parent-app/parent-auth-verification

POST /teachers-app/teacher-auth-verification

POST /web-app/signin

POST /web-app/signup

5. Response Structure

Success: Parent Login (200 OK)

Success: Teacher Login (200 OK)

Success: Admin Signin (200 OK)

Success: Admin Signup (201 Created)

Success: Logout (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