Authentication Module

POST /parent-app/parent-auth-verification
  ├─ Input: { phone_no, pin, fcm_token, device_info }
  ├─ Step 1: Query parent_details WHERE father_phone = phone OR mother_phone = phone
  │    └─ If no record → 401 "Invalid phone number"
  ├─ Step 2: Filter records WHERE pin matches
  │    └─ If no match → 401 "Invalid PIN"
  ├─ Step 3: Collect validParentRecords = pin matches + null-PIN siblings
  ├─ Step 4: Query students table for all linked children
  ├─ Step 5: Generate session_token (UUID) + expiresAt (now + 30 days)
  ├─ Step 6: Insert parent_devices record
  ├─ Step 7: Update parent_details.fcm_token
  ├─ Step 8: Sign JWT payload → return access_token + parent profile + children[]

POST /teachers-app/teacher-auth-verification
  ├─ Input: { phone_no, pin, fcm_token, device_info }
  ├─ Step 1: Query staff WHERE phone_no = input AND skole_id = input.skole_id
  │    └─ If no record → 401
  ├─ Step 2: Verify PIN match
  ├─ Step 3: Insert staff_sessions record
  ├─ Step 4: Sign JWT with type='staff'
  └─ Return access_token + staff profile

POST /web-app/signin
  ├─ Input: { email, password }
  ├─ Step 1: Query users WHERE email = input
  │    └─ If not found → 401
  ├─ Step 2: bcrypt.compare(password, user.password)
  ├─ Step 3: Insert user_sessions record
  ├─ Step 4: Sign JWT with type='user'
  └─ Return access_token + user profile

{
  "phone_no*": "String (10-15 digits, with or without country code)",
  "pin*": "String (4-6 digit PIN)",
  "fcm_token": "String (Firebase Cloud Messaging device token)",
  "device_info": {
    "platform": "String (ios, android, web)",
    "model": "String (device model name)",
    "os_version": "String (operating system version)"
  }
}

{
  "status": "success",
  "message": "Authentication successful",
  "data": {
    "access_token": "JWT token string",
    "session_token": "UUID (unique per device)",
    "expires_in": "2592000 (seconds, 30 days)",
    "token_type": "Bearer",
    "parent": {
      "id": "UUID",
      "skole_id": "UUID",
      "father_phone": "String",
      "mother_phone": "String (nullable)",
      "email": "String (nullable)",
      "pin": "****",
      "father_name": "String",
      "mother_name": "String (nullable)",
      "fcm_token": "String (updated)"
    },
    "children": [
      {
        "id": "UUID",
        "skole_id": "UUID",
        "first_name": "String",
        "last_name": "String",
        "roll_no": "Integer",
        "class": "String",
        "section": "String",
        "status": "active"
      }
    ]
  }
}

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "errors": [
    {"field": "phone_no", "message": "phone_no is required"},
    {"field": "pin", "message": "PIN must be 4-6 digits"}
  ]
}

{
  "status": "error",
  "code": "INVALID_PHONE",
  "message": "Phone number not registered",
  "timestamp": "2026-03-16T10:30:45.000Z"
}

{
  "status": "error",
  "code": "INVALID_PIN",
  "message": "Incorrect PIN",
  "timestamp": "2026-03-16T10:30:45.000Z"
}

{
  "status": "error",
  "code": "RATE_LIMITED",
  "message": "Too many login attempts. Try again in 1 minute",
  "retry_after": 60
}

const loginParent = async (phoneNo, pin, fcmToken) => {
  try {
    const response = await fetch('https://api.skole.com/v1/parent-app/parent-auth-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        phone_no: phoneNo,
        pin: pin,
        fcm_token: fcmToken,
        device_info: {
          platform: 'android',
          model: 'samsung-galaxy-a12',
          os_version: '11.0'
        }
      })
    });

    const data = await response.json();
    
    if (data.status === 'success') {
      const { access_token, session_token, children } = data.data;
      
      // Store token securely (AsyncStorage for React Native)
      await AsyncStorage.setItem('authToken', access_token);
      await AsyncStorage.setItem('sessionToken', session_token);
      
      console.log(`Logged in. Found ${children.length} children`);
      return data.data;
    } else {
      console.error('Login failed:', data.message);
      throw new Error(data.message);
    }
  } catch (error) {
    console.error('Network error:', error);
    throw error;
  }
};

// Usage
await loginParent('9876543210', '1234', 'fcm_token_here');

import requests
import json
import asyncio

async def login_parent(phone_no: str, pin: str, fcm_token: str):
    url = 'https://api.skole.com/v1/parent-app/parent-auth-verification'
    
    payload = {
        'phone_no': phone_no,
        'pin': pin,
        'fcm_token': fcm_token,
        'device_info': {
            'platform': 'ios',
            'model': 'iphone-13',
            'os_version': '15.0'
        }
    }
    
    headers = {'Content-Type': 'application/json'}
    
    try:
        response = requests.post(url, json=payload, headers=headers, timeout=10)
        data = response.json()
        
        if data['status'] == 'success':
            token = data['data']['access_token']
            children = data['data']['children']
            print(f"Logged in successfully. Children: {len(children)}")
            return data['data']
        else:
            raise Exception(f"Login failed: {data['message']}")
    except requests.exceptions.RequestException as e:
        print(f"Network error: {e}")
        raise

# Usage
asyncio.run(login_parent('9876543210', '1234', 'fcm_token_here'))

curl -X POST \
  'https://api.skole.com/v1/parent-app/parent-auth-verification' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_no": "9876543210",
    "pin": "1234",
    "fcm_token": "eZuB8bKWO3c:APA91bH...",
    "device_info": {
      "platform": "android",
      "model": "samsung-a12",
      "os_version": "11.0"
    }
  }'

{
  "logout_all_devices": "Boolean (optional, defaults to false)"
}

{
  "status": "success",
  "message": "Logged out successfully",
  "data": {
    "logged_out_devices": "Integer (1 if logout_all_devices=false, count if true)",
    "timestamp": "2026-03-16T10:30:45.000Z"
  }
}

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header missing or invalid"
}

{
  "status": "error",
  "code": "SESSION_NOT_FOUND",
  "message": "Active session not found"
}

const logoutParent = async (token, logoutAllDevices = false) => {
  try {
    const response = await fetch('https://api.skole.com/v1/parent-app/logout', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        logout_all_devices: logoutAllDevices
      })
    });

    const data = await response.json();
    
    if (data.status === 'success') {
      await AsyncStorage.removeItem('authToken');
      console.log('Logged out successfully');
      return true;
    } else {
      console.error('Logout failed:', data.message);
      return false;
    }
  } catch (error) {
    console.error('Network error:', error);
    throw error;
  }
};

// Usage
await logoutParent(token, false); // Logout from current device
await logoutParent(token, true);  // Logout from all devices

def logout_parent(token: str, logout_all_devices: bool = False) -> bool:
    url = 'https://api.skole.com/v1/parent-app/logout'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    data = {'logout_all_devices': logout_all_devices}
    
    try:
        response = requests.post(url, json=data, headers=headers, timeout=10)
        result = response.json()
        
        if result['status'] == 'success':
            print('Logout successful')
            return True
        else:
            print(f"Logout failed: {result['message']}")
            return False
    except requests.exceptions.RequestException as e:
        print(f"Network error: {e}")
        return False

# Usage
logout_parent(token, logout_all_devices=True)

curl -X POST \
  'https://api.skole.com/v1/parent-app/logout' \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'Content-Type: application/json' \
  -d '{"logout_all_devices": false}'

{
  "fcm_token": "String (Firebase Cloud Messaging token)",
  "platform": "Enum: ios, android, web",
  "model": "String (device model name)",
  "os_version": "String (operating system version)"
}

{
  "status": "success",
  "message": "Device information updated",
  "data": {
    "device_id": "UUID",
    "fcm_token": "Updated token string",
    "platform": "ios",
    "model": "iphone-13-pro",
    "os_version": "15.2",
    "updated_at": "2026-03-16T10:30:45.000Z"
  }
}

{
  "status": "error",
  "code": "INVALID_FCM_TOKEN",
  "message": "FCM token format is invalid or expired"
}

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired JWT token"
}

const updateDeviceInfo = async (token, fcmToken) => {
  try {
    const response = await fetch('https://api.skole.com/v1/parent-app/auth/device-info', {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        fcm_token: fcmToken,
        platform: 'ios',
        model: 'iphone-13-pro',
        os_version: '15.2'
      })
    });

    const data = await response.json();
    if (data.status === 'success') {
      console.log('Device info updated');
      return true;
    } else {
      console.error('Update failed:', data.message);
      return false;
    }
  } catch (error) {
    console.error('Error:', error);
    return false;
  }
};

def update_device_info(token: str, fcm_token: str, platform: str) -> bool:
    url = 'https://api.skole.com/v1/parent-app/auth/device-info'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    data = {
        'fcm_token': fcm_token,
        'platform': platform,
        'model': 'samsung-galaxy-a12',
        'os_version': '11.0'
    }
    
    response = requests.put(url, json=data, headers=headers, timeout=10)
    result = response.json()
    return result['status'] == 'success'

curl -X PUT \
  'https://api.skole.com/v1/parent-app/auth/device-info' \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "fcm_token": "eZuB8bKWO3c:APA91bH...",
    "platform": "android",
    "model": "samsung-a12",
    "os_version": "11.0"
  }'

{
  "phone_no*": "String (10-15 digits)",
  "pin*": "String (4-6 digit PIN)",
  "fcm_token": "String (Firebase token)"
}

{
  "status": "success",
  "message": "Authentication successful",
  "data": {
    "access_token": "JWT token",
    "session_token": "UUID",
    "expires_in": 2592000,
    "token_type": "Bearer",
    "staff": {
      "id": "UUID",
      "skole_id": "UUID",
      "phone_no": "9876543210",
      "email": "teacher@school.com",
      "first_name": "Vikram",
      "last_name": "Kumar",
      "designation": "Teacher",
      "department": "Science",
      "pin": "****"
    },
    "assigned_classes": [
      {
        "class_id": "UUID",
        "class_name": "10-A",
        "subject": "Biology"
      }
    ]
  }
}

{
  "status": "error",
  "code": "INVALID_CREDENTIALS",
  "message": "Phone number or PIN is incorrect"
}

const loginTeacher = async (phoneNo, pin, fcmToken) => {
  const response = await fetch('https://api.skole.com/v1/teachers-app/teacher-auth-verification', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      phone_no: phoneNo,
      pin: pin,
      fcm_token: fcmToken
    })
  });

  const data = await response.json();
  if (data.status === 'success') {
    await AsyncStorage.setItem('teacherToken', data.data.access_token);
    console.log(`Teacher ${data.data.staff.first_name} logged in`);
    return data.data;
  }
  throw new Error(data.message);
};

{
  "logout_all_devices": "Boolean (optional, default: false)"
}

{
  "status": "success",
  "message": "Logged out successfully",
  "data": {
    "logged_out_devices": 1,
    "timestamp": "2026-03-16T10:30:45.000Z"
  }
}

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid JWT token"
}

const logoutTeacher = async (token) => {
  const response = await fetch('https://api.skole.com/v1/teachers-app/logout', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });

  const data = await response.json();
  if (data.status === 'success') {
    await AsyncStorage.removeItem('teacherToken');
    return true;
  }
  return false;
};

{
  "email*": "String (valid email format)",
  "password*": "String (min 8 chars, uppercase, number, special char)",
  "first_name*": "String",
  "last_name*": "String",
  "school_code": "String (optional, for first admin)",
  "invitation_code": "UUID (optional for additional admins)"
}

{
  "status": "success",
  "message": "Admin account created successfully",
  "data": {
    "id": "UUID",
    "email": "admin@school.com",
    "first_name": "Rajesh",
    "last_name": "Sharma",
    "created_at": "2026-03-16T10:30:45.000Z"
  }
}

{
  "status": "error",
  "code": "EMAIL_EXISTS",
  "message": "Email already registered"
}

{
  "status": "error",
  "code": "WEAK_PASSWORD",
  "message": "Password must contain uppercase, number, and special character"
}

{
  "status": "error",
  "code": "INVALID_CODE",
  "message": "School code or invitation code is invalid"
}

const signupAdmin = async (email, password, firstName, lastName, schoolCode) => {
  const response = await fetch('https://api.skole.com/v1/web-app/signup', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email,
      password,
      first_name: firstName,
      last_name: lastName,
      school_code: schoolCode
    })
  });

  const data = await response.json();
  if (data.status === 'success') {
    console.log('Admin account created');
    return data.data;
  }
  throw new Error(data.message);
};

{
  "email*": "String (valid email)",
  "password*": "String",
  "remember_me": "Boolean (optional)"
}

{
  "status": "success",
  "message": "Login successful",
  "data": {
    "access_token": "JWT token",
    "refresh_token": "UUID (if remember_me=true)",
    "expires_in": 86400,
    "token_type": "Bearer",
    "user": {
      "id": "UUID",
      "email": "admin@school.com",
      "first_name": "Rajesh",
      "last_name": "Sharma",
      "role": "admin"
    },
    "school": {
      "id": "UUID",
      "name": "Greenfield Academy",
      "code": "GFA2024"
    }
  }
}

{
  "status": "error",
  "code": "INVALID_CREDENTIALS",
  "message": "Email or password is incorrect"
}

const loginAdmin = async (email, password) => {
  const response = await fetch('https://api.skole.com/v1/web-app/signin', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email,
      password,
      remember_me: true
    })
  });

  const data = await response.json();
  if (data.status === 'success') {
    localStorage.setItem('adminToken', data.data.access_token);
    return data.data;
  }
  throw new Error(data.message);
};

{
  "email*": "String (registered admin email)"
}

{
  "status": "success",
  "message": "Reset link sent to your email",
  "data": {
    "email": "admin@school.com",
    "reset_token_expires_in": "3600 seconds"
  }
}

{
  "status": "error",
  "code": "EMAIL_NOT_FOUND",
  "message": "Email not registered"
}

const requestPasswordReset = async (email) => {
  const response = await fetch('https://api.skole.com/v1/web-app/reset-password', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email })
  });

  const data = await response.json();
  if (data.status === 'success') {
    console.log('Reset email sent');
    return true;
  }
  throw new Error(data.message);
};

{
  "parent_id*": "UUID",
  "activation_code*": "String (from SMS/email invitation)",
  "pin*": "String (4-6 digits only, no special chars)",
  "confirm_pin*": "String (must match pin)"
}

{
  "status": "success",
  "message": "PIN set successfully",
  "data": {
    "parent_id": "UUID",
    "pin_set_at": "2026-03-16T10:30:45.000Z",
    "message": "You can now login with your phone and PIN"
  }
}

{
  "status": "error",
  "code": "INVALID_PIN_FORMAT",
  "message": "PIN must be 4-6 digits only"
}

{
  "status": "error",
  "code": "PIN_MISMATCH",
  "message": "PIN and confirm PIN do not match"
}

{
  "status": "error",
  "code": "INVALID_ACTIVATION_CODE",
  "message": "Activation code is invalid or expired"
}

const setParentPin = async (parentId, activationCode, pin) => {
  const response = await fetch('https://api.skole.com/v1/web-app/parent-set-password', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      parent_id: parentId,
      activation_code: activationCode,
      pin: pin,
      confirm_pin: pin
    })
  });

  const data = await response.json();
  if (data.status === 'success') {
    console.log('PIN set successfully');
    return true;
  }
  throw new Error(data.message);
};

{
  "phone_no*": "String",
  "old_pin*": "String",
  "new_pin*": "String (4-6 digits)",
  "confirm_pin*": "String"
}

{
  "status": "success",
  "message": "PIN updated successfully",
  "data": {
    "updated_at": "2026-03-16T10:30:45.000Z"
  }
}

{
  "status": "error",
  "code": "INVALID_OLD_PIN",
  "message": "Old PIN is incorrect"
}

const updateParentPin = async (phone, oldPin, newPin) => {
  const response = await fetch('https://api.skole.com/v1/web-app/parent-edit-password', {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      phone_no: phone,
      old_pin: oldPin,
      new_pin: newPin,
      confirm_pin: newPin
    })
  });

  const data = await response.json();
  return data.status === 'success';
};

{
  "staff_id*": "UUID",
  "activation_code*": "String",
  "pin*": "String (4-6 digits)",
  "confirm_pin*": "String"
}

{
  "status": "success",
  "message": "PIN set successfully"
}

const setTeacherPin = async (staffId, code, pin) => {
  const response = await fetch('https://api.skole.com/v1/web-app/staff-set-password', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      staff_id: staffId,
      activation_code: code,
      pin: pin,
      confirm_pin: pin
    })
  });

  return (await response.json()).status === 'success';
};

{
  "phone_no*": "String",
  "old_pin*": "String",
  "new_pin*": "String",
  "confirm_pin*": "String"
}

{
  "status": "success",
  "message": "PIN updated successfully"
}

const updateTeacherPin = async (phone, oldPin, newPin) => {
  const response = await fetch('https://api.skole.com/v1/web-app/staff-edit-password', {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      phone_no: phone,
      old_pin: oldPin,
      new_pin: newPin,
      confirm_pin: newPin
    })
  });

  return (await response.json()).status === 'success';
};

{} // Empty body

{
  "status": "success",
  "message": "Logged out successfully"
}

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid JWT token"
}

const logoutAdmin = async (token) => {
  const response = await fetch('https://api.skole.com/v1/web-app/logout', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });

  if (response.ok) {
    localStorage.removeItem('adminToken');
    return true;
  }
  return false;
};