🛡️ Complete Gate Security & Access Control REST API

Gate Security Mobile App REST API

Official API specification for the EduPulse Gate Security, Gatekeeper & Campus Access Control Application. Supports camera-based barcode/QR ID scanning for Students (with automatic parent SMS on gate check-in/out), Staff (GPS shift clock-in/out), Parents (identity verification), Gate Passes (departure & return verification with parent SMS), Visitor logging with digital signature, vehicle parking, directory search, and campus panic alerts.

Base URL http://localhost/edupulse/index.php?api=security

Payload Format application/json (UTF-8)

Auth Header Authorization: Bearer <TOKEN>

Authentication & Security

Protected security endpoints require the Authorization: Bearer <API_TOKEN> HTTP header. Tokens are issued upon authenticating with phone/email and PIN.

// Example Security API Request Header
Authorization: Bearer 18b76c5f7823901a9b23c4d5e6f7890123456789abcdef1234567890abcdef12
Content-Type: application/json

Standard Response Envelope

Success Response (200 OK / 201 Created)

{
  "success": true,
  "status_code": 200,
  "message": "Operation completed successfully",
  "data": { ... },
  "errors": null
}

Error Response (422 Unprocessable / 404 Not Found)

{
  "success": false,
  "status_code": 422,
  "message": "visitor_name, phone, and purpose are required.",
  "data": null,
  "errors": null
}

Module 1

Authentication & Officer Profile

POST ?action=auth_login /auth/login

Public

Authenticates security officer or gatekeeper using phone/email and PIN or password. Returns Bearer token, officer record, and assigned gate post.

Request Payload:

{
  "login": "security@stjulian.edu.ug",
  "password": "1234"
}

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Security officer login successful. Welcome on duty!",
  "data": {
    "token": "18b76c5f7823901a9b23c4d5e6f7890123456789abcdef1234567890abcdef12",
    "user": {
      "id": 29,
      "name": "Officer Samuel Katende",
      "email": "security@stjulian.edu.ug",
      "phone": "+256 772 889 900",
      "role_id": 11,
      "role_name": "security_officer",
      "assigned_gate": "Main Entrance (Gate 1)",
      "school_id": 1,
      "school_name": "St. Julian High School"
    },
    "assigned_gate": "Main Entrance (Gate 1)",
    "school_gates": [
      {
        "id": 1,
        "gate_name": "Main Entrance (Gate 1)",
        "gate_code": "GT-01",
        "description": "Front main gate"
      },
      {
        "id": 2,
        "gate_name": "North Gate (Gate 2)",
        "gate_code": "GT-02",
        "description": "Staff & day scholar gate"
      }
    ]
  }
}

POST ?action=auth_forgot_password /auth/forgot-password

Public

Dispatches 4-digit PIN reset code via SMS to officer's registered phone.

Request Payload:

{ "login": "+256772889900" }

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Password reset verification code dispatched.",
  "data": { "login": "+256772889900", "sms_sent": true, "step": "verify_reset_code" }
}

POST ?action=auth_reset_password /auth/reset-password

Public

Request Payload:

{ "login": "+256772889900", "otp_code": "9142", "new_password": "4321" }

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Password reset successfully! You are now logged in.",
  "data": { "token": "a1b2c3d4e5f67890...", "user": { "id": 29, "name": "Officer Samuel Katende" } }
}

POST ?action=auth_logout /auth/logout

Bearer Token

Sample Response (`200 OK`):

{ "success": true, "status_code": 200, "message": "Logged out successfully.", "data": null }

GET ?action=profile /profile

Bearer Token

Retrieves full security officer profile and assigned gate post information.

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Security officer profile retrieved",
  "data": {
    "user": {
      "id": 29,
      "name": "Officer Samuel Katende",
      "email": "security@stjulian.edu.ug",
      "phone": "+256 772 889 900",
      "assigned_gate": "Main Entrance (Gate 1)",
      "role_name": "security_officer",
      "photo_url": "uploads/security/sec_29.jpg"
    },
    "assigned_gate": "Main Entrance (Gate 1)",
    "school": {
      "name": "St. Julian High School",
      "logo_url": "uploads/logos/school_logo_1.png"
    }
  }
}

POST ?action=select_active_gate /profile/select-gate

Bearer Token

Request Payload:

{ "gate_name": "North Gate (Gate 2)" }

Sample Response (`200 OK`):

{ "success": true, "status_code": 200, "message": "Active gate post changed to North Gate (Gate 2)", "data": { "assigned_gate": "North Gate (Gate 2)" } }

GET ?action=security_badge /security-badge

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Security officer digital badge retrieved",
  "data": {
    "staff": {
      "id": 29,
      "officer_code": "SEC-OFFICER-29",
      "name": "Officer Samuel Katende",
      "role": "Chief Campus Security Officer",
      "assigned_gate": "Main Entrance (Gate 1)",
      "phone": "+256 772 889 900"
    },
    "barcode_data": "SEC-OFFICER-29",
    "qr_string": "EDUPULSE-SECURITY:29:SEC-OFFICER-29:SCH-1"
  }
}

Module 2

Gate Security Dashboard & Live Census

GET ?action=dashboard /dashboard

Bearer Token

Real-time gate security overview: Today's visitors, currently inside count, checked out count, student gate scans today, active gate passes departed, active incidents, and assigned gate post.

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Gate security dashboard overview retrieved",
  "data": {
    "metrics": {
      "today_visitors": 14,
      "inside_visitors": 4,
      "checked_out_today": 10,
      "today_student_scans": 420,
      "active_departed_passes": 2,
      "pending_gate_passes": 1,
      "active_incidents": 0,
      "assigned_gate": "Main Entrance (Gate 1)"
    },
    "school_gates": [
      { "id": 1, "gate_name": "Main Entrance (Gate 1)", "gate_code": "GT-01" },
      { "id": 2, "gate_name": "North Gate (Gate 2)", "gate_code": "GT-02" }
    ],
    "unread_notifications": 0,
    "open_chats": 0
  }
}

Module 3

Universal Gate ID Scanner (Student, Staff, Parent & Pass)

POST ?action=scan_id /scan/id

Bearer Token

Universal scanner endpoint supporting 4 entities: (1) Student check-in/out + parent SMS, (2) Staff shift clock-in/out, (3) Parent verification + visitor logging, (4) Gate pass clearance + departed/returned parent SMS.

Request Payload:

{
  "scanned_code": "STU-2026-008",
  "gate_name": "Main Entrance (Gate 1)"
}

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Mukibi Henry (Senior 1) checked IN at Main Entrance (Gate 1) at 07:15 AM.",
  "data": {
    "type": "student",
    "action": "check_in",
    "name": "Mukibi Henry",
    "code": "STU-2026-008",
    "class_name": "Senior 1",
    "gate_name": "Main Entrance (Gate 1)",
    "timestamp": "07:15 AM",
    "photo_url": "uploads/students/stu_8.jpg",
    "parent_notified": true
  }
}

Module 4

Visitor Registration & Management

POST ?action=visitor_log /visitors/log-entry

Bearer Token

Request Payload:

{
  "visitor_name": "Eng. David Kigozi",
  "phone": "+256 702 445 566",
  "national_id": "CM902837482930",
  "purpose": "Solar Power Inspection & Maintenance",
  "person_to_see": "Bursar / Head Teacher",
  "vehicle_number": "UBF 912X",
  "gate_name": "Main Entrance (Gate 1)",
  "notes": "Carrying electrical toolbox and multimeters",
  "signature_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAYIA..."
}

Sample Response (`201 Created`):

{
  "success": true,
  "status_code": 201,
  "message": "Visitor entry for Eng. David Kigozi logged at Main Entrance (Gate 1) successfully!",
  "data": {
    "log_id": 18,
    "visitor_name": "Eng. David Kigozi",
    "phone": "+256 702 445 566",
    "national_id": "CM902837482930",
    "purpose": "Solar Power Inspection & Maintenance",
    "person_to_see": "Bursar / Head Teacher",
    "vehicle_number": "UBF 912X",
    "gate_name": "Main Entrance (Gate 1)",
    "time_in": "2026-08-30 10:15:00",
    "status": "Inside"
  }
}

GET ?action=visitors_active /visitors/active

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Active visitors inside campus retrieved",
  "data": [
    {
      "id": 18,
      "visitor_name": "Eng. David Kigozi",
      "phone": "+256 702 445 566",
      "purpose": "Solar Power Inspection & Maintenance",
      "vehicle_number": "UBF 912X",
      "gate_name": "Main Entrance (Gate 1)",
      "time_in": "2026-08-30 10:15:00",
      "status": "Inside"
    }
  ]
}

POST ?action=visitor_checkout /visitors/checkout

Bearer Token

Request Payload:

{ "log_id": 18, "time_out": "2026-08-30 12:45:00", "checkout_notes": "Exited campus cleanly" }

Sample Response (`200 OK`):

{ "success": true, "status_code": 200, "message": "Visitor checked out successfully.", "data": { "log_id": 18, "time_out": "2026-08-30 12:45:00", "status": "CheckedOut" } }

GET ?action=visitor_details&log_id=18 /visitors/details

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Visitor details retrieved",
  "data": {
    "id": 18,
    "visitor_name": "Eng. David Kigozi",
    "phone": "+256 702 445 566",
    "national_id": "CM902837482930",
    "purpose": "Solar Power Inspection & Maintenance",
    "person_to_see": "Bursar / Head Teacher",
    "vehicle_number": "UBF 912X",
    "time_in": "2026-08-30 10:15:00",
    "time_out": "2026-08-30 12:45:00",
    "status": "CheckedOut",
    "notes": "Exited campus cleanly with tools inspected",
    "signature_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAYIA...",
    "officer_name": "Officer Samuel Katende",
    "officer_phone": "+256 772 889 900"
  }
}

GET ?action=visitor_history&limit=30 /visitors/history

Bearer Token

Module 5

Vehicle Access & Parking Control

POST ?action=vehicle_log /vehicles/log-entry

Bearer Token

Request Payload:

{
  "vehicle_number": "UBA 452K",
  "driver_name": "Tr. Samuel Katende",
  "phone": "+256 772 112 233",
  "purpose": "School Bus Route Return",
  "gate_name": "Delivery & Bus Gate (Gate 3)",
  "notes": "Route 3 Morning run complete"
}

Sample Response (`201 Created`):

{
  "success": true,
  "status_code": 201,
  "message": "Vehicle UBA 452K logged into campus at Delivery & Bus Gate (Gate 3)!",
  "data": { "log_id": 19, "vehicle_number": "UBA 452K", "time_in": "2026-08-30 08:30:00", "status": "Inside" }
}

GET ?action=vehicles_active /vehicles/active

Bearer Token

POST ?action=vehicle_checkout /vehicles/checkout

Bearer Token

Request Payload:

{ "vehicle_number": "UBA 452K" }

Sample Response (`200 OK`):

{ "success": true, "status_code": 200, "message": "Vehicle departure marked successfully.", "data": null }

Module 6

Student Gate Passes & Leave Clearance

GET ?action=gate_passes&status=Approved /gate-passes/list

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Gate passes list retrieved",
  "data": [
    {
      "id": 6,
      "pass_number": "GP-2026-5794",
      "student_id": 8,
      "first_name": "mukibi",
      "last_name": "hr",
      "admission_no": "ADM/2026/875",
      "class_name": "Primary 1",
      "destination": "Kampala Hospital Clinic",
      "reason": "Hardship Waiver & Medical Treatment",
      "departure_time": "2026-08-30 11:00:00",
      "return_date": "2026-08-30 17:00:00",
      "parent_name": "Eduvix",
      "parent_contact": "0755575803",
      "status": "Approved",
      "photo_url": "uploads/students/stu_8.jpg"
    }
  ]
}

GET ?action=gate_pass_verify&pass_number=GP-2026-5794 /gate-passes/verify

Bearer Token

POST ?action=gate_pass_depart /gate-passes/depart

Bearer Token

Request Payload:

{ "pass_id": 6, "gate_name": "Main Entrance (Gate 1)" }

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Student mukibi hr marked DEPARTED cleanly at Main Entrance (Gate 1).",
  "data": { "pass_id": 6, "pass_number": "GP-2026-5794", "status": "Departed", "departed_at": "2026-08-30 11:15:00" }
}

POST ?action=gate_pass_return /gate-passes/return

Bearer Token

Request Payload:

{ "pass_id": 6, "gate_name": "Main Entrance (Gate 1)" }

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Student mukibi hr return verified at Main Entrance (Gate 1).",
  "data": { "pass_id": 6, "pass_number": "GP-2026-5794", "status": "Returned", "returned_at": "2026-08-30 16:30:00" }
}

Module 7

Student, Parent & Staff Directory Lookup

GET ?action=search_students&query=Mukibi /students/search

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Student search results",
  "data": [
    {
      "id": 8,
      "first_name": "mukibi",
      "last_name": "hr",
      "student_code": "STU-2026-008",
      "admission_no": "ADM/2026/875",
      "student_type": "Day",
      "photo_url": "uploads/students/stu_1785314836_679.jpg",
      "class_name": "Primary 1",
      "stream_name": "Stream A",
      "parent_name": "Eduvix",
      "parent_phone": "0755575803"
    }
  ]
}

GET ?action=search_parents&query=Sarah /parents/search

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Parent search results",
  "data": [
    {
      "id": 4,
      "full_name": "Sarah RUKUNDO",
      "phone": "0772122164",
      "email": "sarah@gmail.com",
      "parent_code": "PRN-2026-004",
      "photo_url": "uploads/parents/prn_4.jpg",
      "children": [
        { "id": 8, "first_name": "mukibi", "last_name": "hr", "class_name": "Primary 1" }
      ]
    }
  ]
}

GET ?action=search_staff&query=Teacher /staff/search

Bearer Token

Module 8

Campus Incident Reporting & Resolution

POST ?action=incident_report /incidents/report

Bearer Token

Request Payload:

{
  "title": "Unauthorized Night Trespasser Near Perimeter Fence",
  "incident_type": "Perimeter Breach",
  "location": "North Fence near Sports Pavilion",
  "severity_level": "High",
  "description": "Patrol officers intercepted an individual attempting to jump the perimeter fence."
}

Sample Response (`201 Created`):

{
  "success": true,
  "status_code": 201,
  "message": "Security incident recorded and dispatched to school administration!",
  "data": { "incident_id": 21, "title": "Unauthorized Night Trespasser Near Perimeter Fence", "severity": "High" }
}

GET ?action=incidents_active /incidents/active

Bearer Token

POST ?action=incident_resolve /incidents/resolve

Bearer Token

Request Payload:

{ "incident_id": 21, "resolution_notes": "Suspect escorted off campus by local police patrol." }

Module 9

Gate Posts & Officers Directory

GET ?action=gates /gates/list

Bearer Token

Module 10

Shift GPS Attendance & Clock-In

POST ?action=attendance_clock_in /attendance/clock-in

Bearer Token

Request Payload:

{ "latitude": 0.3541, "longitude": 32.5912 }

Module 11

Salary & Shift Allowances

GET ?action=payroll_summary /payroll/summary

Bearer Token

Module 12

Messaging & Staff Chat

GET ?action=chats /chats

Bearer Token

Module 13

Circulars & Alerts

GET ?action=notifications /notifications

Bearer Token

Module 14

Academic Calendar & Events

GET ?action=calendar_events /calendar/events

Bearer Token

Module 15

Emergency Panic Dispatch & Hotlines

POST ?action=emergency_panic /emergency/panic-report

SOS Panic Dispatch

Request Payload:

{
  "emergency_type": "Armed Intrusion / Gate Riot",
  "gate_location": "Main Entrance (Gate 1)",
  "latitude": 0.3541,
  "longitude": 32.5912,
  "notes": "Urgent security backup requested at front gate."
}

Sample Response (`201 Created`):

{
  "success": true,
  "status_code": 201,
  "message": "Emergency panic broadcast dispatched to school administration, head teacher and security agencies!",
  "data": { "incident_id": 22, "emergency_type": "Armed Intrusion / Gate Riot", "status": "Dispatched" }
}

SDK Code Examples

React Native / TypeScript Integration securityApi.ts

import axios from 'axios';

const BASE_URL = 'http://localhost/edupulse/index.php?api=security';
export const securityApi = axios.create({ baseURL: BASE_URL });

export const setSecurityAuthToken = (token: string) => {
  securityApi.defaults.headers.common['Authorization'] = `Bearer ${token}`;
};

// 1. Universal Scanner
export const scanGateId = async (scannedCode: string, gateName: string) => {
  const res = await securityApi.post('&action=scan_id', {
    scanned_code: scannedCode,
    gate_name: gateName,
  });
  return res.data;
};

// 2. Mark Gate Pass Departed
export const departGatePass = async (passId: number, gateName: string) => {
  const res = await securityApi.post('&action=gate_pass_depart', {
    pass_id: passId,
    gate_name: gateName,
  });
  return res.data;
};

Flutter / Dart Integration security_api_service.dart

import 'dart:convert';
import 'package:http/http.dart' as http;

class SecurityApiService {
  static const String baseUrl = 'http://localhost/edupulse/index.php?api=security';
  String? _authToken;

  void setToken(String token) {
    _authToken = token;
  }

  Map<String, String> get _headers => {
    'Content-Type': 'application/json',
    if (_authToken != null) 'Authorization': 'Bearer $_authToken',
  };

  // 1. Universal Barcode / QR Scanner
  Future<Map<String, dynamic>> scanCode(String code, String gateName) async {
    final response = await http.post(
      Uri.parse('$baseUrl&action=scan_id'),
      headers: _headers,
      body: jsonEncode({
        'scanned_code': code,
        'gate_name': gateName,
      }),
    );
    return jsonDecode(response.body);
  }

  // 2. Mark Gate Pass Departed
  Future<Map<String, dynamic>> markPassDeparted(int passId, String gateName) async {
    final response = await http.post(
      Uri.parse('$baseUrl&action=gate_pass_depart'),
      headers: _headers,
      body: jsonEncode({
        'pass_id': passId,
        'gate_name': gateName,
      }),
    );
    return jsonDecode(response.body);
  }
}