Access Control Guide

This guide covers how to configure and manage access control in GxP, including access points, zones, and credential scanning.

Overview

GxP's access control system enables you to:

• Define access points (entry/exit locations)
• Create access zones with capacity limits
• Control who can access each zone
• Track real-time access events
• Generate access reports

Key Concepts

Access Points

Physical or virtual locations where credentials are scanned (e.g., doors, kiosks, turnstiles).

Access Zones

Logical areas that access points lead to (e.g., "Main Hall", "VIP Lounge", "Backstage").

Readers

Devices that scan credentials at access points.

Credentials

Identification tokens assigned to attendees (barcodes, QR codes, RFID cards, NFC).

Access Points

List Access Points

curl -X GET "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/access-points" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": 1,
      "name": "Main Entrance",
      "slug": "main-entrance",
      "access_zone_id": 1,
      "direction": "in",
      "is_active": true,
      "readers": [
        {
          "id": 1,
          "identifier": "READER-001",
          "type": "barcode"
        }
      ]
    }
  ]
}

Get Access Point Details

curl -X GET "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/access-points/{accessPointId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Access Zones

Access zones define areas within your event venue.

Zone Properties

Property	Description
name	Zone display name
slug	URL-friendly identifier
capacity	Maximum occupancy (null = unlimited)
current_count	Current number of people in zone
requires_ticket	Whether zone requires specific ticket type

Capacity Tracking

GxP automatically tracks zone capacity based on access events:

{
  "data": {
    "id": 1,
    "name": "VIP Lounge",
    "capacity": 100,
    "current_count": 45,
    "available": 55
  }
}

Access Control Flow

1. Credential Scan

When a credential is scanned at an access point:

Credential Scan → Lookup Attendee → Check Permissions → Grant/Deny Access

2. Permission Check

The system verifies:

1. Credential is valid and assigned to an attendee
2. Attendee type has access to the zone
3. Zone capacity is not exceeded
4. Time restrictions are satisfied
5. No blacklist/blocklist entries

3. Access Result

Based on the checks, access is either granted or denied, triggering corresponding events.

Real-time Access Events

Subscribe to access events via WebSocket:

// Subscribe to all access events for a project
Echo.private(`dashboard.project.${projectSlug}.access`)
  .listen('AccessGranted', (e) => {
    console.log('Access granted:', e.attendee, e.access_point);
  })
  .listen('AccessDenied', (e) => {
    console.log('Access denied:', e.reason, e.access_point);
  });

AccessGranted Event Payload

{
  "attendee_id": 12345,
  "attendee": {
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "access_point_id": 1,
  "access_zone_id": 1,
  "credential_id": 100,
  "timestamp": "2024-01-15T14:30:00Z"
}

AccessDenied Event Payload

{
  "credential_value": "ABC123",
  "access_point_id": 1,
  "reason": "not_authorized",
  "timestamp": "2024-01-15T14:31:00Z"
}

Denial Reasons

Reason	Description
invalid_credential	Credential not found in system
not_authorized	Attendee type lacks zone access
expired	Credential has expired
capacity_exceeded	Zone is at maximum capacity
time_restricted	Access outside allowed time window
blocklisted	Attendee is on blocklist

Reader Configuration

Reader Authentication

Readers authenticate using OTP (One-Time Password):

# Request OTP for reader login
curl -X POST "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/readers/login" \
  -H "Content-Type: application/json" \
  -d '{
    "reader_identifier": "READER-001"
  }'

Verify OTP

curl -X POST "https://api.gramercy.cloud/api/v1/reader-otp/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "otp": "123456",
    "reader_identifier": "READER-001"
  }'

Access Reports

Generate access reports for analysis:

Zone Occupancy Over Time

curl -X POST "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/analytics/metrics" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "zone_occupancy",
    "zone_id": 1,
    "start_date": "2024-01-15T00:00:00Z",
    "end_date": "2024-01-15T23:59:59Z",
    "interval": "hour"
  }'

Access Activity Summary

curl -X POST "https://api.gramercy.cloud/api/v1/projects/{teamSlug}/{projectSlug}/analytics/metrics" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "metric": "access_summary",
    "start_date": "2024-01-15T00:00:00Z",
    "end_date": "2024-01-15T23:59:59Z"
  }'

Webhooks

Configure webhooks to receive access events:

curl -X POST "https://api.gramercy.cloud/api/v1/webhook/subscribe" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/gxp",
    "events": ["access.granted", "access.denied"],
    "project_id": 123
  }'

See the Webhooks documentation for more details.

Best Practices

1. Set appropriate capacities: Configure zone capacities to prevent overcrowding
2. Use time restrictions: Limit access to specific time windows when needed
3. Monitor real-time: Subscribe to WebSocket events for live monitoring
4. Configure fallbacks: Set up offline mode for readers in case of connectivity issues
5. Regular audits: Review access logs periodically for security