Authentication Guide
🔑 Global HTTP Headers 📱 Flutter & Dart Dio Client
API Categories
📌 Authentication & JWT Rotation📌 Dashboard & KPIs📌 Leads Management📌 Deals Pipeline📌 Tasks & Checklist📌 Users & Profile📌 Organizations Management

REST API Reference & Integration Portal

Stateless JSON REST API backend for TotalSchoolERP CRM and Flutter mobile applications. Authenticated purely via Authorization: Bearer JWT access token header without session cookies or UI redirects.

🔑 Global Authentication Headers

All endpoints under /api/* are 100% stateless and require no session cookies or CSRF tokens. Provide your application API key in the request headers.

Header Name Type Required? Description
Authorization String (Required) YES JWT Bearer access token obtained from /api/login or /api/refresh (Format: Bearer eyJhbGciOi...). Required for all protected API endpoints.
X-API-KEY String (Required for /api/login) YES Secret application API key required during initial authentication at /api/login. Default: TSERP_SECRET_KEY_2026
Content-Type String (Required for POST) YES Must be application/json.
Accept String (Required) YES Must be application/json.

📱 Flutter & Dart Dio Client Example

Copy this stateless Dio configuration directly into your Flutter app to connect without session cookie interceptors.

// lib/core/network/api_client.dart
import 'package:dio/dio.dart';

class ApiClient {
  static final Dio dio = Dio(BaseOptions(
    baseUrl: 'https://crm.totalschoolerp.in',
    connectTimeout: const Duration(seconds: 15),
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'X-API-KEY': 'TSERP_SECRET_KEY_2026', // Required for initial /api/login
    },
  ));

  // Call after successful login or token refresh to attach JWT Bearer token to subsequent calls
  static void setAuthToken(String accessToken) {
    dio.options.headers['Authorization'] = 'Bearer $accessToken';
  }

  static void clearAuthToken() {
    dio.options.headers.remove('Authorization');
  }
}

⚡ Authentication & JWT Rotation

Stateless JWT login, Refresh token rotation, and MFA verification endpoints.

POST /api/login

Authenticate user credentials with email and password. Returns JWT access token (1 hour expiry) and Refresh token (30 days expiry).

⚡ Required Headers
X-API-KEY: TSERP_SECRET_KEY_2026
Content-Type: application/json
📦 Request Payload (JSON)
{
    "email": "rajesh.kumar@totalschoolerp.in",
    "password": "password123"
}
🟢 200 OK Response Example
{
    "success": true,
    "mfa_required": false,
    "token_type": "Bearer",
    "access_token": "eyJhbGciOi...",
    "expires_in": 3600,
    "refresh_token": "a8f9d0c1e2b3a4f5d6c7e8f90123456789abcdef0123456789abcdef01234567",
    "user": {
        "id": 105,
        "full_name": "Rajesh Kumar",
        "email": "rajesh.kumar@totalschoolerp.in",
        "role": "sales_rep",
        "designation": "Senior Sales Executive"
    },
    "api_headers": {
        "Authorization": "Bearer eyJhbGciOi...",
        "X-API-KEY": "TSERP_SECRET_KEY_2026",
        "X-USER-ID": 105
    }
}
curl -X POST "https://crm.totalschoolerp.in/api/login" \
  -H "X-API-KEY: TSERP_SECRET_KEY_2026" \
  -H "Content-Type: application/json" \
  -d '{"email":"rajesh.kumar@totalschoolerp.in","password":"password123"}'
POST /api/refresh

Exchange a valid refresh token for a new JWT access token and rotated refresh token without logging in again.

⚡ Required Headers
Content-Type: application/json
📦 Request Payload (JSON)
{
    "refresh_token": "a8f9d0c1e2b3a4f5d6c7e8f90123456789abcdef0123456789abcdef01234567"
}
🟢 200 OK Response Example
{
    "success": true,
    "message": "Token refreshed successfully",
    "token_type": "Bearer",
    "access_token": "eyJhbGciOi...",
    "expires_in": 3600,
    "refresh_token": "b9e0c1f2a3..."
}
curl -X POST "https://crm.totalschoolerp.in/api/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"a8f9d0c1e2b3a4f5d6c7e8f90123456789abcdef0123456789abcdef01234567"}'
POST /api/logout

Revoke refresh token and terminate user session statelessly in database.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
📦 Request Payload (JSON)
{
    "refresh_token": "b9e0c1f2a3..."
}
🟢 200 OK Response Example
{
    "success": true,
    "message": "Logged out successfully."
}
curl -X POST "https://crm.totalschoolerp.in/api/logout" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"b9e0c1f2a3..."}'
POST /api/mfa

Verify 6-digit Google Authenticator OTP code if mfa_required is true. Returns JWT token pair.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
📦 Request Payload (JSON)
{
    "user_id": 105,
    "code": "123456"
}
🟢 200 OK Response Example
{
    "success": true,
    "message": "MFA verification successful.",
    "token_type": "Bearer",
    "access_token": "eyJhbGciOi...",
    "expires_in": 3600,
    "refresh_token": "a8f9d0c1e2b3...",
    "user": {
        "id": 105,
        "full_name": "Rajesh Kumar",
        "role": "sales_rep"
    }
}
curl -X POST "https://crm.totalschoolerp.in/api/mfa" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"user_id":105,"code":"123456"}'

⚡ Dashboard & KPIs

Executive summary analytics and KPI metrics.

GET /api/dashboard

Retrieve performance metrics (pipeline value, target progress, won deals), pending task count, and recent interactions.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
🟢 200 OK Response Example
{
    "success": true,
    "user": {
        "id": 105,
        "full_name": "Rajesh Kumar",
        "role": "sales_rep"
    },
    "metrics": {
        "pipeline_value": 450000,
        "won_value": 120000,
        "total_deals": 8,
        "conversion_rate": 25
    },
    "targetValue": 200000,
    "targetProgress": 60,
    "recent_tasks": [
        {
            "id": 12,
            "title": "Follow up with DPS Principal",
            "due_date": "2026-07-26",
            "priority": "high"
        }
    ],
    "recent_interactions": [
        {
            "id": 5,
            "school_name": "Delhi Public School",
            "type": "meeting",
            "notes": "Demo scheduled"
        }
    ]
}
curl -X GET "https://crm.totalschoolerp.in/api/dashboard" \
  -H "Authorization: Bearer eyJhbGciOi..."

⚡ Leads Management

CRUD operations and status workflows for educational institution leads.

GET /api/leads

List all leads assigned to the authenticated user or all leads if admin.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
🟢 200 OK Response Example
{
    "success": true,
    "count": 2,
    "leads": [
        {
            "id": 1,
            "school_name": "Delhi Public School",
            "city": "New Delhi",
            "status": "contacted",
            "lead_score": 85
        }
    ]
}
curl -X GET "https://crm.totalschoolerp.in/api/leads" \
  -H "Authorization: Bearer eyJhbGciOi..."
GET /api/leads/detail?id=1

Retrieve full lead profile including interaction history and notes.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
🟢 200 OK Response Example
{
    "success": true,
    "lead": {
        "id": 1,
        "school_name": "Delhi Public School",
        "contact_person": "Dr. Sharma",
        "phone": "9876543210"
    },
    "interactions": [
        {
            "id": 1,
            "interaction_date": "2026-07-20 14:30:00",
            "type": "call",
            "notes": "Discussed ERP modules"
        }
    ]
}
curl -X GET "https://crm.totalschoolerp.in/api/leads/detail?id=1" \
  -H "Authorization: Bearer eyJhbGciOi..."
POST /api/leads/add

Create a new prospective school lead.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
📦 Request Payload (JSON)
{
    "school_name": "St. Xaviers High School",
    "contact_person": "Father Anthony",
    "phone": "9811223344",
    "email": "principal@stxaviers.edu",
    "city": "Mumbai",
    "state": "Maharashtra",
    "student_count": 2500
}
🟢 200 OK Response Example
{
    "success": true,
    "message": "Lead created successfully.",
    "lead_id": 15
}
curl -X POST "https://crm.totalschoolerp.in/api/leads/add" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"school_name":"St. Xaviers High School","contact_person":"Father Anthony","phone":"9811223344","email":"principal@stxaviers.edu","city":"Mumbai","state":"Maharashtra","student_count":2500}'
POST /api/leads/update-status

Update the sales pipeline status of a lead.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
📦 Request Payload (JSON)
{
    "lead_id": 1,
    "status": "qualified"
}
🟢 200 OK Response Example
{
    "success": true,
    "message": "Lead status updated."
}
curl -X POST "https://crm.totalschoolerp.in/api/leads/update-status" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"lead_id":1,"status":"qualified"}'

⚡ Deals Pipeline

Manage revenue opportunities and deal progression stages.

GET /api/deals

Retrieve all active deals grouped by stage (Discovery, Proposal, Negotiation, Won, Lost).

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
🟢 200 OK Response Example
{
    "success": true,
    "deals": [
        {
            "id": 101,
            "deal_name": "DPS Cloud ERP Implementation",
            "stage": "proposal",
            "value": 150000,
            "probability": 60
        }
    ]
}
curl -X GET "https://crm.totalschoolerp.in/api/deals" \
  -H "Authorization: Bearer eyJhbGciOi..."
POST /api/deals/add

Create a new deal opportunity linked to a lead.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
📦 Request Payload (JSON)
{
    "lead_id": 1,
    "deal_name": "Annual License & Support",
    "value": 120000,
    "stage": "discovery",
    "expected_close_date": "2026-08-30"
}
🟢 200 OK Response Example
{
    "success": true,
    "message": "Deal added successfully.",
    "deal_id": 102
}
curl -X POST "https://crm.totalschoolerp.in/api/deals/add" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"lead_id":1,"deal_name":"Annual License & Support","value":120000,"stage":"discovery","expected_close_date":"2026-08-30"}'
POST /api/deals/update-stage

Move a deal to a new stage in the sales pipeline.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
📦 Request Payload (JSON)
{
    "deal_id": 101,
    "stage": "won"
}
🟢 200 OK Response Example
{
    "success": true,
    "message": "Deal stage updated to won."
}
curl -X POST "https://crm.totalschoolerp.in/api/deals/update-stage" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"deal_id":101,"stage":"won"}'
POST /api/deals/delete

Remove a deal from the pipeline.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
📦 Request Payload (JSON)
{
    "deal_id": 101
}
🟢 200 OK Response Example
{
    "success": true,
    "message": "Deal deleted."
}
curl -X POST "https://crm.totalschoolerp.in/api/deals/delete" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"deal_id":101}'

⚡ Tasks & Checklist

Manage sales rep action items, follow-ups, and daily tasks.

GET /api/tasks

Get all pending and completed tasks assigned to the user.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
🟢 200 OK Response Example
{
    "success": true,
    "tasks": [
        {
            "id": 1,
            "title": "Send quotation to DPS",
            "due_date": "2026-07-26",
            "status": "pending",
            "priority": "high"
        }
    ]
}
curl -X GET "https://crm.totalschoolerp.in/api/tasks" \
  -H "Authorization: Bearer eyJhbGciOi..."
POST /api/tasks/add

Create a new task.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
📦 Request Payload (JSON)
{
    "title": "Schedule product demo with Trustees",
    "due_date": "2026-07-28",
    "priority": "medium",
    "lead_id": 1
}
🟢 200 OK Response Example
{
    "success": true,
    "message": "Task created successfully.",
    "task_id": 5
}
curl -X POST "https://crm.totalschoolerp.in/api/tasks/add" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Schedule product demo with Trustees","due_date":"2026-07-28","priority":"medium","lead_id":1}'
POST /api/tasks/toggle

Toggle task completion status between pending and completed.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
📦 Request Payload (JSON)
{
    "task_id": 1
}
🟢 200 OK Response Example
{
    "success": true,
    "status": "completed",
    "message": "Task marked as completed."
}
curl -X POST "https://crm.totalschoolerp.in/api/tasks/toggle" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"task_id":1}'

⚡ Users & Profile

Team management, user profiles, and two-factor authentication.

GET /api/profile

Retrieve logged-in user profile, monthly commission target, and 2FA status.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
🟢 200 OK Response Example
{
    "success": true,
    "user": {
        "id": 105,
        "full_name": "Rajesh Kumar",
        "email": "rajesh.kumar@totalschoolerp.in",
        "role": "sales_rep",
        "monthly_target": 200000,
        "commission_rate": 5,
        "google_2fa_enabled": 1
    }
}
curl -X GET "https://crm.totalschoolerp.in/api/profile" \
  -H "Authorization: Bearer eyJhbGciOi..."
POST /api/profile/disable-2fa

Disable Google Authenticator 2FA for the current user.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
🟢 200 OK Response Example
{
    "success": true,
    "message": "Two-Factor Authentication disabled."
}
curl -X POST "https://crm.totalschoolerp.in/api/profile/disable-2fa" \
  -H "Authorization: Bearer eyJhbGciOi..."
GET /api/users

List all CRM users (Admin only).

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
🟢 200 OK Response Example
{
    "success": true,
    "users": [
        {
            "id": 105,
            "full_name": "Rajesh Kumar",
            "email": "rajesh.kumar@totalschoolerp.in",
            "role": "sales_rep",
            "is_active": 1
        }
    ]
}
curl -X GET "https://crm.totalschoolerp.in/api/users" \
  -H "Authorization: Bearer eyJhbGciOi..."
POST /api/users/add

Provision a new CRM user account (Admin only).

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
📦 Request Payload (JSON)
{
    "full_name": "Anita Desai",
    "email": "anita.desai@totalschoolerp.in",
    "password": "SecurePass2026!",
    "role": "sales_rep",
    "designation": "Regional Sales Manager",
    "department": "Sales",
    "phone": "9822334455",
    "monthly_target": 250000
}
🟢 200 OK Response Example
{
    "success": true,
    "message": "User created successfully.",
    "user_id": 106
}
curl -X POST "https://crm.totalschoolerp.in/api/users/add" \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Anita Desai","email":"anita.desai@totalschoolerp.in","password":"SecurePass2026!","role":"sales_rep","designation":"Regional Sales Manager","department":"Sales","phone":"9822334455","monthly_target":250000}'

⚡ Organizations Management

Manage client school ERP organizations and view institution details.

GET /api/organizations

Retrieve all school ERP organizations and their basic status.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
🟢 200 OK Response Example
{
    "success": true,
    "organizations": [
        {
            "organization_id": 1,
            "organization_name": "Delhi Public School",
            "city": "New Delhi",
            "state": "Delhi",
            "org_active": 1
        }
    ]
}
curl -X GET "https://crm.totalschoolerp.in/api/organizations" \
  -H "Authorization: Bearer eyJhbGciOi..."
GET /api/organizations/details?id=1

Retrieve comprehensive details of a client school organization including database schema status and session dates.

⚡ Required Headers
Authorization: Bearer eyJhbGciOi...
🟢 200 OK Response Example
{
    "success": true,
    "organization": {
        "organization_id": 1,
        "org_uuid": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
        "organization_name": "Delhi Public School",
        "org_email": "admin@dps.edu.in",
        "org_phone": "+91 11 23456789",
        "city": "New Delhi",
        "state": "Delhi",
        "subscription_plan": "Enterprise",
        "hostname": "srv1.totalschoolerp.in",
        "db_name": "erp_dps",
        "db_active": 1
    }
}
curl -X GET "https://crm.totalschoolerp.in/api/organizations/details?id=1" \
  -H "Authorization: Bearer eyJhbGciOi..."