XcodeSol Security Guard Admin Documentation

Devices and Biometrics

When attendance mode is set to With devices, physical biometric devices (fingerprint scanners, face recognition terminals, NFC readers) send check-in and check-out data to the application via API.

Architecture

text
┌─────────────────┐     ┌──────────────────────┐     ┌───────────────────────┐
│  Biometric       │     │  Local Agent /       │     │  Security Guard       │
│  Device          │────▶│  Device HTTP Client  │────▶│  Admin API            │
│  (fingerprint,   │     │  (runs on-site PC)   │     │  POST /api/devices/   │
│   face, NFC)     │     │                      │     │  attendance           │
└─────────────────┘     └──────────────────────┘     └───────────────────────┘

The device (or a local agent connected to it via SDK/USB/serial) calls the API with the biometric identifier and the system matches it to the enrolled guard.

Device Registration

1. Go to Operations > Devices. 2. Click Add device. 3. Enter a unique Code and a descriptive Name (e.g., "Main Gate Fingerprint"). 4. Select the Type — Biometric, Fingerprint, Face, or NFC. 5. Select the Location where the device is installed. 6. Set the Status (Active / Inactive). 7. Click Save.

After saving, the system automatically generates a unique API token for the device. Copy this token and configure it on the device or local agent.

Regenerate Token

If a device token is compromised, click the key icon next to the device in the list to regenerate a new token. The old token is immediately invalidated.

Biometric Enrollment

Before guards can check in, their biometric data must be enrolled.

1. Go to Operations > Guard Biometrics. 2. Click Enroll biometric. 3. Select the Guard. 4. Select the Type — Fingerprint, Face, or NFC. 5. Enter the Identifier — this is the template ID, user ID, or NFC UID provided by the device when the guard first scans. 6. Set the Enrolled date (defaults to today). 7. Set Status to Active. 8. Click Save.

Each guard can have at most one active enrollment per biometric type.

Enrollment Workflow

text
1. Guard places finger on device → device creates template "FP_USER_042"
2. Device/agent displays the template ID to the admin
3. Admin enters guard=Ahmed, type=fingerprint, identifier="FP_USER_042" in Guard Biometrics
4. Two records are linked: (fingerprint + FP_USER_042) → guard Ahmed

Device Check-In Flow

When a guard scans their biometric at the device:

1. The device sends:

text
   POST /api/devices/attendance

with JSON body:

json
   {
     "device_token": "DEVICE_API_TOKEN",
     "biometric_type": "fingerprint",
     "identifier": "FP_USER_042",
     "type": "check_in",
     "timestamp": "2026-07-01T08:00:00Z"
   }

2. The backend:

  • Validates the device token.
  • Looks up guard_biometrics matching type = fingerprint AND identifier = FP_USER_042.
  • Finds the linked guard (e.g., Ahmed, guard_id = 5).
  • Creates or updates attendance for that guard on the given date with:
  • status = Present
  • check_in_at = 2026-07-01 08:00:00
  • device_id = the registered device
  • biometric_type = fingerprint

3. For check_out, the same endpoint updates the existing record's check_out_at timestamp.

API Token Authentication

Unlike user authentication (which uses Sanctum bearer tokens), devices authenticate using their api_token field sent in the request body. This allows devices that cannot handle HTTP headers to still send attendance data.

Example cURL Commands

Check-in

powershell
curl -X POST https://your-app.com/api/devices/attendance `
  -H "Content-Type: application/json" `
  -d '{
    "device_token": "TOKEN_HERE",
    "biometric_type": "fingerprint",
    "identifier": "FP_USER_042",
    "type": "check_in",
    "timestamp": "2026-07-01T08:00:00Z"
  }'

Check-out

powershell
curl -X POST https://your-app.com/api/devices/attendance `
  -H "Content-Type: application/json" `
  -d '{
    "device_token": "TOKEN_HERE",
    "biometric_type": "fingerprint",
    "identifier": "FP_USER_042",
    "type": "check_out",
    "timestamp": "2026-07-01T17:00:00Z"
  }'

Response

On success, the API returns:

json
{
  "message": "Attendance recorded successfully.",
  "attendance": {
    "guard_id": 5,
    "date": "2026-07-01",
    "status": "Present",
    "check_in_at": "2026-07-01T08:00:00.000000Z",
    "check_out_at": null,
    "device_id": 1,
    "biometric_type": "fingerprint"
  }
}

Device Health

The last_ping_at field on the device record is updated automatically with each attendance request. You can use this to monitor whether a device is online and functioning.

PreviousConfigurationNextFAQ