Building Access Integration

Digital ID provides a JSON API endpoint for turnstile systems, building access control panels, and automated access verification. This allows organisations to use Digital ID cards for secure building entry and automatic access logging.

How It Works

When an employee scans their Digital ID QR code at an access point:

1. The turnstile or access panel scans the QR code
2. The system extracts the verification token from the QR code
3. The access system calls the Digital ID API endpoint
4. Digital ID verifies the token and employee status
5. The API returns success or failure response
6. Access is granted or denied based on the response
7. All access attempts are logged for security monitoring

API Endpoint

The Building Access API endpoint is available at:

https://lightslategrey-weasel-963972.hostingersite.com/api/verify-token.php

Request Methods

The API supports both GET and POST requests:

GET Request

GET /api/verify-token.php?token=XXX&type=qr&location=Main_Entrance&device_id=TURNSTILE_01

POST Request (JSON)

POST /api/verify-token.php
Content-Type: application/json

{
  "token": "abc123...",
  "type": "qr",
  "location": "Building_A_Floor_2",
  "device_id": "ACCESS_PANEL_03"
}

Request Parameters

Response Format

Success Response (200 OK)

{
  "success": true,
  "valid": true,
  "employee": {
    "id": 123,
    "employee_reference": "EMP001",
    "display_reference": "EMP001",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "organisation_id": 1,
    "organisation_name": "Example Organisation",
    "is_active": true
  },
  "id_card": {
    "id": 456,
    "expires_at": "2025-12-31 23:59:59"
  },
  "verification_type": "qr",
  "verified_at": "2025-01-15T10:30:00+00:00",
  "message": "Verification successful"
}

Failure Response (403 Forbidden)

{
  "success": false,
  "valid": false,
  "message": "Verification token has expired. Please request a new one.",
  "error": "expired",
  "verified_at": "2025-01-15T10:30:00+00:00"
}

Error Codes

Integration Guide

To integrate Digital ID with your turnstile or building access system:

Step 1: Extract Token from QR Code

When an employee scans their QR code, the access system should:

1. Scan the QR code image
2. Extract the URL (format: https://lightslategrey-weasel-963972.hostingersite.com/verify.php?token=XXX)
3. Parse the token parameter from the URL

Step 2: Call the API

Make an HTTP request to the verification endpoint:

GET https://lightslategrey-weasel-963972.hostingersite.com/api/verify-token.php?token=XXX&type=qr&location=Main_Entrance&device_id=TURNSTILE_01

Step 3: Process Response

Based on the API response:

• If success: true and valid: true: Grant access
• If success: false or valid: false: Deny access
• Log the access attempt (success or failure) for audit purposes

Step 4: Handle Errors

Common error scenarios:

• Expired Token: QR codes expire after 5 minutes. The employee should refresh their ID card page to get a new QR code.
• Revoked Card: The employee's ID card has been revoked by an administrator. Access should be denied.
• Inactive Employee: The employee is no longer active. Access should be denied.
• Network Error: If the API is unreachable, consider implementing a fallback mechanism or offline mode.

Security Features

• Time-Limited Tokens: QR code tokens expire after 5 minutes to prevent replay attacks
• Automatic Logging: All access attempts are logged with location and device information
• Real-Time Verification: Employee status is checked in real-time (active/inactive, revoked cards)
• Organisation Isolation: Each organisation's data is completely isolated
• Optional API Key Authentication: Can be enabled for additional security

Access Logging

All access attempts are automatically logged in the Digital ID system with:

• Employee information (name, reference)
• Verification type (QR, NFC, BLE)
• Verification result (success/failed)
• Timestamp
• Location (if provided)
• Device ID (if provided)
• IP address

Organisation administrators can view and export these logs from the Verification Logs page, with filtering by location and device ID.

Optional API Key Authentication

For enhanced security, you can enable API key authentication:

1. Set REQUIRE_API_KEY_FOR_VERIFICATION=1 in your environment configuration
2. Create an API key in your organisation settings
3. Include the API key in requests:
   • Header: X-API-Key: your-api-key
   • Or parameter: ?api_key=your-api-key

Example Integration Code

Here's a simple example of how to integrate with the API:

Python Example

import requests
import urllib.parse

def verify_access(qr_code_url, location, device_id):
    # Extract token from QR code URL
    parsed = urllib.parse.urlparse(qr_code_url)
    params = urllib.parse.parse_qs(parsed.query)
    token = params.get('token', [None])[0]
    
    if not token:
        return False, "No token found in QR code"
    
    # Call verification API
    api_url = "https://lightslategrey-weasel-963972.hostingersite.com/api/verify-token.php"
    response = requests.get(api_url, params={
        'token': token,
        'type': 'qr',
        'location': location,
        'device_id': device_id
    })
    
    if response.status_code == 200:
        data = response.json()
        if data.get('success') and data.get('valid'):
            return True, f"Access granted for {data['employee']['full_name']}"
        else:
            return False, data.get('message', 'Verification failed')
    else:
        return False, f"API error: {response.status_code}"

# Usage
success, message = verify_access(
    qr_code_url="https://lightslategrey-weasel-963972.hostingersite.com/verify.php?token=abc123",
    location="Main_Entrance",
    device_id="TURNSTILE_01"
)
if success:
    # Grant access
    open_turnstile()
else:
    # Deny access
    deny_access(message)

Support

For integration support or questions about the Building Access API, contact your organisation administrator or refer to the Troubleshooting guide.