🚀 OmniWatch API Documentation

Version 1.0.0 | Last Updated: February 2026

🔐 Authentication

The OmniWatch API uses JWT (JSON Web Token) for authentication. After a successful login, you will receive a token that must be included in the header of subsequent requests.

Getting Started

To authenticate with the OmniWatch API:

Call POST /api/login with phone and password
Receive the JWT token in the response
Include the token in the Authorization header for protected routes

        # Authorization Header Format

Authorization: Bearer

👤 Auth Endpoints

POST /api/register PUBLIC

Request Body

Parameter	Type	Required	Description
firstName	string	Yes	User's first name
lastName	string	Yes	User's last name
phone	string	Yes	Phone number (e.g., +254712345678)
password	string	Yes	Account password (min 6 characters)
role	string	No	User role (default: "guard")
companyCode	string	No	Company/invite code

Example Request

        curl -X POST http://localhost:5000/api/register \

  -H "Content-Type: application/json" \

  -d '{

    "firstName": "John",

    "lastName": "Doe",

    "phone": "+254712345678",

    "password": "securepassword123",

    "role": "guard"

  }'

Example Response

        {

  "message": "User registered successfully",

  "user": {

    "id": "abc123",

    "name": "John Doe",

    "phone": "+254712345678",

    "role": "guard"

  }

}

Status Codes: 201 Created 400 Bad Request 409 Conflict 500 Internal Server Error

POST /api/login PUBLIC

Authenticate and receive JWT token

Request Body

Parameter	Type	Required	Description
phone	string	Yes	Registered phone number
password	string	Yes	Account password

Example Request

        curl -X POST http://localhost:5000/api/login \

  -H "Content-Type: application/json" \

  -d '{

    "phone": "+254712345678",

    "password": "securepassword123"

  }'

Example Response

        {

  "message": "Login successful",

  "user": {

    "id": "abc123",

    "name": "John Doe",

    "phone": "+254712345678",

    "role": "guard",

    "company_code": "COMP001"

  },

  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

}

Status Codes: 200 OK 400 Bad Request 401 Unauthorized 500 Internal Server Error

POST /api/logout PUBLIC

End user session and logout

Example Request

        curl -X POST http://localhost:5000/api/logout \

  -H "Content-Type: application/json" \

  -c cookies.txt

Example Response

{ "message": "Logout successful" }

Status Codes: 200 OK 500 Internal Server Error

GET /api/me PROTECTED

Get current authenticated user information

Headers

Header	Value
Authorization	Bearer

Example Request

        curl -X GET http://localhost:5000/api/me \

  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example Response

        {

  "authenticated": true,

  "user": {

    "id": "abc123",

    "name": "John Doe",

    "phone": "+254712345678",

    "role": "guard"

  }

}

Status Codes: 200 OK 401 Unauthorized

POST /api/verify-token PUBLIC

Verify if a JWT token is valid

Request Body

Parameter	Type	Required	Description
token	string	Yes	JWT token to verify

Example Request

        curl -X POST http://localhost:5000/api/verify-token \

  -H "Content-Type: application/json" \

  -d '{ "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }'

Example Response

        {

  "valid": true,

  "user": {

    "id": "abc123",

    "name": "John Doe",

    "role": "guard"

  }

}

Status Codes: 200 OK 400 Bad Request 401 Unauthorized

🛡️ Protected Routes

The following routes require authentication. Include the JWT token in the Authorization header.

GET /api/admin/dashboard PROTECTED

Admin dashboard data (requires any authenticated user)

Example Request

        curl -X GET http://localhost:5000/api/admin/dashboard \

  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example Response

        {

  "message": "Welcome to the admin dashboard",

  "user": { "id": "abc123", "name": "John Doe" },

  "data": {

    "totalGuards": 45,

    "activeShifts": 12,

    "pendingReports": 5

  }

}

🧭 Admin Management APIs

These endpoints are used by the admin dashboard to manage guards, assignments, and locations. All are scoped to the authenticated admin's organization via invite_code.

GET /api/admin/guards PROTECTED

List all guards in the admin organization, enriched with latest assignment and patrol-derived online/last-seen data.

Response Fields (per guard)

Field	Type	Description
id	string	Guard user ID
first_name	string	Guard first name
last_name	string	Guard last name
phone	string	Guard phone number
location	string	Resolved location name from latest assignment
location_id	string	Location ID from latest assignment
assigned_areas	string	Comma-separated assigned areas
operating_hours_start	string	Assignment start time
operating_hours_end	string	Assignment end time
is_online	boolean	`true` when latest patrol is active and not ended
last_seen	string\|null	Latest patrol `end_time` or fallback access time
last_seen_display	string	`"Online (Currently on patrol)"` when active, otherwise timestamp or `"Never"`

Example Request

        curl -X GET http://localhost:5000/api/admin/guards \

  -H "Authorization: Bearer <token>"

Example Response

        {

  "guards": [

    {

      "id": "f3a9...",

      "first_name": "Jane",

      "last_name": "Doe",

      "phone": "+2547...",

      "location": "Main Gate",

      "location_id": "8b2a...",

      "is_online": true,

      "last_seen_display": "Online (Currently on patrol)"

    }

  ]

}

DELETE /api/admin/guards/:id PROTECTED

Remove a guard from the organization and cascade-delete related records by user_id from assignments, logs, and patrols.

Path Params

Parameter	Type	Required	Description
id	string	Yes	Guard user ID

Example Request

        curl -X DELETE http://localhost:5000/api/admin/guards/f3a9... \

  -H "Authorization: Bearer <token>"

Example Response

        {

  "message": "Guard removed successfully",

  "deleted": {

    "assignments": 2,

    "logs": 8,

    "patrols": 5

  }

}

Status Codes: 200 OK 400 Bad Request 401 Unauthorized 404 Not Found 500 Internal Server Error

POST /api/admin/assignments PROTECTED

Create a new assignment for a guard in the same organization.

Request Body

Parameter	Type	Required	Description
user_id	string	Yes	Guard user ID
location	string	Yes	Location ID
assigned_areas	string	Yes	Comma-separated areas/checkpoints
start_time	string	Yes	Assignment start time (e.g., `09:00`)
end_time	string	Yes	Assignment end time (e.g., `17:00`)

Example Request

        curl -X POST http://localhost:5000/api/admin/assignments \

  -H "Authorization: Bearer <token>" \

  -H "Content-Type: application/json" \

  -d '{

    "user_id": "f3a9...",

    "location": "8b2a...",

    "assigned_areas": "Gate A, Lobby",

    "start_time": "09:00",

    "end_time": "17:00"

  }'

Example Response

        {

  "message": "Assignment created successfully",

  "assignment": {

    "id": "a7bc...",

    "user_id": "f3a9...",

    "location": "8b2a..."

  }

}

GET /api/admin/locations PROTECTED

List all locations in the authenticated admin organization.

Example Response

        {

  "locations": [

    {

      "id": "8b2a...",

      "name": "Main Gate",

      "assigned_areas": "Gate A, Gate B"

    }

  ]

}

POST /api/admin/locations PROTECTED

Create a location for the admin organization.

Request Body

Parameter	Type	Required	Description
name	string	Yes	Location name
assigned_areas	string	No	Comma-separated areas

Example Response

        {

  "message": "Location created successfully",

  "location": {

    "id": "8b2a...",

    "name": "Main Gate"

  }

}

PATCH /api/admin/locations/:id PROTECTED

Update location fields (name and/or assigned_areas) within the admin organization.

Request Body

Parameter	Type	Required	Description
name	string	No	Updated location name (cannot be empty)
assigned_areas	string	No	Updated areas list

Example Response

        {

  "message": "Location updated successfully",

  "location": {

    "id": "8b2a...",

    "name": "Rear Gate"

  }

}

DELETE /api/admin/locations/:id PROTECTED

Delete a location in the admin organization.

Example Response

        {

  "message": "Location deleted successfully",

  "id": "8b2a..."

}

🛰️ Guard App APIs

Endpoints used by the guard page for assignments, patrol lifecycle, location tracking, and logs.

GET /api/my-assignments PROTECTED

Fetch assignments for the authenticated guard.

Example Response

{

  "assignments": [

    { "id": "asg1", "user_id": "u1", "location": "loc1", "assigned_areas": "Gate A, Lobby", "start_time": "09:00", "end_time": "17:00" }

  ]

}

PUT /api/my-assignments PROTECTED

Update the authenticated guard's assignment details.

Request Body

Parameter	Type	Required	Description
location	string	Yes	Location ID
assigned_areas	string	Yes	Comma-separated areas
start_time	string	Yes	Shift start time
end_time	string	Yes	Shift end time

Example Response

{ "message": "Assignment updated successfully" }

GET /api/locations PROTECTED

Fetch all locations in the authenticated user's organization.

Example Response

{

  "locations": [

    { "id": "loc1", "name": "Main Gate", "assigned_areas": "Gate A, Gate B" }

  ]

}

GET /api/patrols PROTECTED

Fetch guard patrol history.

Query Params

Parameter	Type	Required	Description
limit	number	No	Max records (default: 10)
sort	string	No	Sort order (default: `-start_time`)

Example Response

{ "patrols": [ { "id": "p1", "status": "active" } ] }

POST /api/patrols PROTECTED

Start a patrol session.

Request Body

Parameter	Type	Required	Description
start_time	string	Yes	Patrol start timestamp
user_id	string	Yes	Guard user ID
organization_id	string	No	Organization ID
duration	number	No	Initial duration in minutes
end_time	string	No	End time if already completed
map	string	No	Serialized path data
location_data	array	No	Location points (alternative to `map`)

Example Response

{ "message": "Patrol started successfully", "data": { "id": "p1", "status": "active" } }

PATCH /api/patrols/:id PROTECTED

Update patrol details, including ending a patrol by setting end_time and optionally status.

Request Body

Parameter	Type	Required	Description
duration	number	No	Patrol duration in minutes
end_time	string	No	Patrol end timestamp
map	string	No	Serialized route data
location_data	array	No	Route points (mapped to `map`)
status	string	No	Patrol state (e.g., active/completed)

Example Response

{ "message": "Patrol updated successfully", "data": { "id": "p1" } }

PATCH /api/patrols/:id/location PROTECTED

Append incremental GPS points to an active patrol route.

Request Body

Parameter	Type	Required	Description
location_data	array	Yes	Array of points: `{ latitude, longitude, timestamp }`

Example Response

{ "message": "Location updated successfully", "points_count": 120 }

GET /api/logs PROTECTED

Fetch logs created by the authenticated guard.

Query Params

Parameter	Type	Required	Description
limit	number	No	Max records (default: 50)
sort	string	No	Sort order (default: `-timestamp`)

Example Response

{ "logs": [ { "id": "l1", "title": "Checkpoint" } ] }

POST /api/logs PROTECTED

Create a new guard log entry with optional images and patrol linkage.

Request Body

Parameter	Type	Required	Description
title	string	Yes	Log title
description	string	Yes	Log details
category	string	Yes	One of: activity, unusual, incident, checkpoint, other
images	string\|array	No	Image data/URIs (commonly JSON string)
patrol_id	string	No	Related patrol ID

Example Response

{ "message": "Log created successfully", "data": { "id": "l1" } }

🧩 Additional APIs

GET /api/assignments PROTECTED

Fetch assignment records from backend storage.

Example Response

{ "assignments": [ { "id": "asg1" } ] }

GET /api/organizations/invite-codes PROTECTED

Return invite codes for registered organizations.

Example Response

{ "inviteCodes": ["ORG001", "ORG002"] }

POST /api/organizations/validate-invite-code PUBLIC

Validate whether an organization invite code exists.

Request Body

Parameter	Type	Required	Description
inviteCode	string	Yes	Organization invite code

Example Response

{ "valid": true, "message": "Invite code is valid" }

GET /api/admin/patrols PROTECTED

Admin patrol feed across all guards in organization, enriched with guard name and checkpoints.

Query Params

Parameter	Type	Required	Description
limit	number	No	Max records (default: 50)
sort	string	No	Sort by timestamp (default: `-start_time`)

Example Response

{ "patrols": [ { "id": "p1", "guard_name": "Jane Doe" } ] }

GET /api/admin/logs PROTECTED

Admin logs feed across all guards in organization with location resolution.

Query Params

Parameter	Type	Required	Description
limit	number	No	Max records (default: 50)
sort	string	No	Sort by timestamp (default: `-timestamp`)

Example Response

{ "logs": [ { "id": "l1", "location": "Main Gate" } ] }

⚠️ Error Handling

All error responses follow a consistent format:

      {

  "error": "Error Type",

  "message": "Human readable error message"

}

Common Error Codes

Status	Error	Description
400	Validation Error	Missing required fields or invalid data
401	Unauthorized	Invalid credentials or no token provided
403	Forbidden	Access denied for this resource
409	Conflict	User already exists (duplicate entry)
500	Internal Server Error	Server-side error

📱 Frontend Integration

React Native / Expo Example

      // Login Example

const login = async (phone, password) => {

  const response = await fetch('http://localhost:5000/api/login', {

    method: 'POST',

    headers: {

      'Content-Type': 'application/json',

    },

    body: JSON.stringify({ phone, password }),

  });

  const data = await response.json();

  if (data.token) {

    // Store token securely

    AsyncStorage.setItem('token', data.token);

  }

  return data;

};

// Protected API Call

const getDashboard = async () => {

  const token = await AsyncStorage.getItem('token');

  const response = await fetch('http://localhost:5000/api/admin/dashboard', {

    headers: {

      'Authorization': `Bearer ${token}`,

    },

  });

  return response.json();

};

🔧 Environment Variables

Create a .env file in the backend root with the following variables:

      # Server

APIPORT=5000

NODE_ENV=development

# JWT Secret (change this in production!)

JWT_SECRET=your-super-secret-jwt-key-change-in-production

# Directus Configuration

DIRECTUS_URL=http://your-directus-instance.com

DIRECTUS_TOKEN=your-directus-static-token

# PostgreSQL Database

DB_USER=postgres

DB_HOST=localhost

DB_NAME=omniwatch

DB_PASSWORD=your-password

DB_PORT=5432