Access hardware command, event, and check-in bridge lifecycle runbook

Access hardware command, event, and check-in bridge lifecycle runbook explains what happens after Matrix COSEC, ZKTeco, or Suprema setup: how staff-triggered commands are dispatched, how provider events are verified and stored, when a member check-in is created, and which failure states must remain evidence instead of being treated as a successful entry.

What this page is for

Who should use it

Owner, implementation, operations manager, front desk lead, platform admin, support

Where to find it

Admin / Biometric Setting, access-control commands, access-event callbacks, Check-in

Before you start

Access hardware command, event, and check-in bridge lifecycle runbook
Access operation starts from an active ACCESS_CONTROL device and records provider MATRIX_COSEC or ZKTECO or SUPREMA, linked gym/location, externalDeviceId, serialNumber, command endpoint, callback verifier, fakeModeEnabled state, commandRetryAttempts, commandRetryDelayMs, staff actor, personId when syncing, reason, commandRequestId, and disabled reason when operation is not allowed
Open gate and Sync person commands send one backend-created provider request with commandRequestId/idempotencyKey, commandType, provider, deviceId, externalDeviceId, serialNumber, personId when present, reason, and requestedByStaffUserId to the configured middleware endpoint when fake mode is off
Access command dispatch must record provider HTTP status/body, retry attempts, retryable failure decisions, final COMPLETED or FAILED command status, audit row, and must not report simulated success when fake mode is off and the endpoint is missing
Access-event ingestion accepts only POST /commerce/devices/:deviceId/access/events from an active access-control device and requires configured token or HMAC verification unless fake mode is enabled before creating AccessEvent rows
Access event person resolution must use same-brand personId or externalRef/accessIdentifier/userId/cardId/cardNo/cardNumber/employeeCode/pin/uid/identifier and must preserve unmatched identifiers as evidence instead of creating a cross-brand check-in
Allowed access events may create Scheduling check-in source ACCESS_CONTROL only after person resolution and backend check-in eligibility pass, then annotate AccessEvent payload with jamesonCheckIn CREATED, checkInEventId, and source
Denied, blocked, rejected, failed, invalid, unauthorized, unmatched, or non-check-in access events must remain AccessEvent evidence with jamesonCheckIn SKIPPED or no bridge annotation and must not create a successful check-in
If provider access was granted but Scheduling check-in fails because entitlement, location, duplicate, booking, or backend policy rejects it, the AccessEvent must remain stored with jamesonCheckIn FAILED and backend error for staff investigation
Access hardware operation secret handling forbids exposing bearer tokens, API keys, session ids, event HMAC secrets, callback tokens, custom headers, command endpoint URLs, raw provider command responses, raw access callback payloads, or biometric/card identifiers in mobile, support, analytics, crash logs, or public docs

Daily workflow

Start from the active access-control device in Admin / Biometric Setting. Confirm provider MATRIX_COSEC, ZKTECO, or SUPREMA, linked gym/location, externalDeviceId, serialNumber, status, fakeModeEnabled state, command endpoint readiness, callback verifier readiness, commandRetryAttempts, commandRetryDelayMs, and the disabled reason shown when any required value is missing.
For Open gate, staff must choose the correct device/location and enter a reason when the workflow requires it. SquareOS creates the command record, commandRequestId, and idempotencyKey first, then dispatches the provider request only from the backend.
For Sync person, staff must start from the backend person record and selected active device. The provider request includes personId, commandType SYNC_PERSON, device identity, reason, requestedByStaffUserId, commandRequestId, and idempotencyKey; mobile or support tools must not write biometric/card enrollment state locally.
When fake mode is on, SquareOS may create simulated completed command evidence for demo or setup training. When fake mode is off, a missing endpoint records a failed command and must not be shown as a successful gate open or person sync.
When fake mode is off and an endpoint exists, SquareOS posts generic JSON to commandEndpointUrl, openGateEndpointUrl, or syncPersonEndpointUrl. The adapter must translate that JSON into Matrix COSEC, ZKTeco, or Suprema SDK/API calls and must honor commandRequestId/idempotencyKey before retries are enabled.
Retryable command failures include network failures and retryable HTTP responses such as 408, 409, 425, 429, 500, 502, 503, and 504. Every attempt, provider status/body summary, retry decision, retry delay, and final COMPLETED or FAILED status should be visible to support without leaking raw credentials.
Access events enter SquareOS through POST /commerce/devices/:deviceId/access/events. The device must be active and type ACCESS_CONTROL; live callbacks must pass the configured shared-token or HMAC verifier before an AccessEvent row is created.
The callback may identify a person by same-brand personId, externalRef, accessIdentifier, userId, cardId, cardNo, cardNumber, employeeCode, pin, uid, identifier, or equivalent payload field. If no same-brand person can be resolved, SquareOS stores the event evidence and identifier instead of creating a cross-brand check-in.
Allowed, granted, entry, or check-in events can bridge to Scheduling check-in only after person resolution and normal backend eligibility checks pass. The AccessEvent payload then records jamesonCheckIn CREATED, checkInEventId, and source ACCESS_CONTROL.
Denied, blocked, rejected, failed, invalid, unauthorized, unmatched, duplicate-only, heartbeat, door-status, or non-check-in events remain access evidence. They should show jamesonCheckIn SKIPPED or no bridge annotation and must not create a successful check-in.
If the provider grants access but Scheduling rejects the check-in because entitlement, location, duplicate, booking, or another backend policy fails, SquareOS must keep the AccessEvent and annotate jamesonCheckIn FAILED with the backend error for staff investigation.
Certification evidence should include one live Open gate command, one Sync person command, one allowed event that creates check-in when eligible, one denied event that stays skipped, and one unmatched or policy-rejected event that proves failure evidence is retained. If hardware is not available, record accepted limitation and keep live actions disabled.
Support troubleshooting should compare device id, provider, linked location, staff actor, command id, commandRequestId, retry attempts, callback verification result, event id, external identifier, matched person, checkInEventId, jamesonCheckIn status, audit id, and Staff app deep link before changing any operational state.

Watch out

Do not expose bearer tokens, API keys, session ids, callback tokens, HMAC secrets, custom headers, command endpoint URLs, raw provider command responses, raw access callback payloads, biometric templates, card numbers, or full device portal screenshots in mobile, support, analytics, crash logs, or public launch notes.
Do not claim a live gate opened from fake-mode simulated command evidence. Fake mode proves workflow shape only.
Do not retry Open gate unless the adapter owner has proven idempotency for commandRequestId/idempotencyKey; otherwise one SquareOS action can physically open the gate more than once.
Do not let mobile create local access success, local check-in success, local sync-person enrollment, or callback replay. Mobile may only show backend-returned state and Staff app deep links.
Do not treat generic HTTP 200 from middleware as full certification. Production proof needs command evidence, verified callback evidence, mapped person evidence, denied/unmatched evidence, bridge outcome evidence, and owner/support sign-off.

Use the left menu to open related pages in Start Here.
Use Ask Docs for questions that are already covered in this public documentation.