Skip to main content
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

PropertyValue
Endpoint GroupAuthentication Services
HTTP MethodsPOST, PUT, PATCH
Base Paths/parent-app, /teachers-app, /web-app
Primary TechNestJS + JWT + Prisma

​
Core Auth Endpoints

MethodRouteAuthDescription
POST/parent-app/parent-auth-verification🔓 PublicParent login (Phone/Email + PIN)
POST/teachers-app/teacher-auth-verification🔓 PublicTeacher/Staff login (Phone + PIN)
POST/web-app/signin🔓 PublicAdmin login (Email + Password)
POST/web-app/signup🔓 PublicAdmin registration
POST/web-app/logout🔐 JWTInvalidate 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: 
{
  "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"
}

​
POST /web-app/signin

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

​
POST /web-app/signup

Request Body: 
{
  "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 
{
  "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 
{
  "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 
{
  "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 
{
  "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 CodeError CodeDescription
401UNAUTHORIZEDInvalid phone number or PIN
403FORBIDDENAccount disabled or school access revoked
400BAD_REQUESTMissing required fields (e.g., skole_id)
500SERVER_ERRORInternal 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.