Matrix COSEC, ZKTeco, and Suprema access hardware setup runbook

Matrix COSEC, ZKTeco, and Suprema access hardware setup runbook explains how to register gym gates and biometric/access devices in SquareOS, what to collect from the vendor or integrator, how command dispatch and event callbacks are verified, and what must stay disabled until real-device certification is completed.

What this page is for

Who should use it

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

Where to find it

Matrix COSEC admin/API or integrator sheet, ZKTeco ZKBioTime/BioTime or middleware, Suprema BioStar X/BioStar 2 or middleware, SquareOS Admin / Biometric Setting

Before you start

Matrix COSEC, ZKTeco, and Suprema access hardware setup runbook: complete one extraction row and one command/event evidence row for every physical gate, turnstile, door, or biometric access device before staff rely on gate-open or check-in automation.
Matrix COSEC setup records controller id, device id, site or branch id, door or access group, push/API mode, user identifier format, command endpoint URL, event callback URL, callback token or HMAC secret, and COSEC partner ticket when values come from an integrator.
ZKTeco setup records ZKBioTime or BioTime server/base URL, API credential or token reference, device serial number, terminal id, area/location mapping, employee code or card/user identifier format, command endpoint URL, event push or polling adapter URL, and callback verifier.
Suprema setup records BioStar X or BioStar 2 server/base URL, device id, door id, access group id, user id/card identifier format, session or token credential reference, event log/push adapter URL, command endpoint URL, and callback verifier.
SquareOS access hardware fields map provider values to Commerce Device type ACCESS_CONTROL, provider MATRIX_COSEC or ZKTECO or SUPREMA, name, code, externalDeviceId, serialNumber, linked gym/location, metadata commandEndpointUrl/openGateEndpointUrl/syncPersonEndpointUrl, authToken, headers, accessEventWebhookSecret or accessEventWebhookToken, commandRetryAttempts, commandRetryDelayMs, fakeModeEnabled, and active status.
Live gate-open and sync-person proof requires an active access-control device, fake mode off, configured command endpoint, commandRequestId/idempotencyKey, provider request/response, retry attempt record, final COMPLETED or FAILED command, audit row, and no simulated completion when endpoint is missing.
Access event ingestion proof requires POST /commerce/devices/:deviceId/access/events from an active access-control device with token or HMAC verification unless safe/fake mode is enabled, matched personId or externalRef/accessIdentifier/userId/cardId/cardNo/cardNumber/employeeCode/pin/uid/identifier, accessCallbackVerification, AccessEvent id, and check-in bridge state.
Allowed access events may create Scheduling check-in source ACCESS_CONTROL only after same-brand person resolution and backend eligibility rules pass; denied, blocked, rejected, failed, invalid, unauthorized, unmatched, or policy-failed events must remain AccessEvent evidence with jamesonCheckIn SKIPPED or FAILED and must not create a successful check-in.
Real-device certification can be completed later, but the runbook must record the configured provider account/device, physical gate/location, middleware or adapter owner, endpoint URLs, verifier rule, idempotency/retry rule, disabled-state copy, fake-mode state, and owner accepted limitation before handoff.
Access hardware secret handling forbids exposing COSEC/ZKTeco/Suprema bearer tokens, API keys, session ids, event HMAC secrets, callback tokens, custom headers, raw callback payloads, or credential screenshots in launch notes, mobile screens, support tickets, analytics, or crash logs.
Because SquareOS sends generic JSON commands to the configured endpoint, vendor-specific COSEC, ZKTeco, or Suprema SDK payload translation must be owned by the configured middleware/adapter and verified before staff rely on gate-open, sync-person, staff-attendance, or check-in automation.

Daily workflow

Confirm the physical access design first: which gate, door, turnstile, biometric reader, or controller belongs to which SquareOS gym/location, and whether the gym uses Matrix COSEC, ZKTeco, Suprema, or a partner middleware that fronts those devices.
For Matrix COSEC, open the COSEC admin/API tooling or the integrator onboarding sheet. Record controller id, device id, site/branch id, door/access group, push/API mode, user identifier format, command endpoint URL, event callback URL, callback token or HMAC secret, and the COSEC partner ticket id when values are delivered by an integrator instead of a self-serve portal.
For ZKTeco, open ZKBioTime/BioTime or the middleware handoff. Record server/base URL, API credential or token reference, device serial number, terminal id, area/location mapping, employee code/card/user identifier format, command endpoint URL, event push or polling adapter URL, and callback token or HMAC verifier. Do not put the raw API credential in launch notes.
For Suprema, open BioStar X/BioStar 2 or the middleware handoff. Record server/base URL, device id, door id, access group id, user id/card identifier format, session or token credential reference, event log/push adapter URL, command endpoint URL, and callback verifier. If BioStar uses a short-lived session id, record how the middleware refreshes it instead of storing the session in SquareOS notes.
In SquareOS Admin / Biometric Setting, create a Commerce Device with type ACCESS_CONTROL, provider MATRIX_COSEC, ZKTECO, or SUPREMA, name, stable code, externalDeviceId, serialNumber, linked gym/location, and active status only when the physical device belongs to that location and is meant to be usable.
In access-device metadata, enter commandEndpointUrl when one middleware endpoint handles all commands, or openGateEndpointUrl and syncPersonEndpointUrl when the adapter exposes separate routes. Enter authToken and headers only in write-only/admin fields, and use headers for site code, tenant id, branch id, or adapter-specific routing values.
Enter accessEventWebhookSecret when the access adapter signs POST /commerce/devices/:deviceId/access/events with HMAC-SHA256, or accessEventWebhookToken when it sends a shared token in x-webhook-token, x-access-token, x-access-control-token, or x-jameson-token. Signature headers supported by SquareOS are x-access-signature, x-access-control-signature, x-zkteco-signature, x-cosec-signature, x-suprema-signature, and x-signature.
Keep fakeModeEnabled on during setup. With fake mode on, SquareOS can simulate Open gate and Sync person for workflow demos. With fake mode off, SquareOS requires a configured command endpoint and records FAILED instead of simulated success when the endpoint is missing.
Keep commandRetryAttempts at 1 for Open gate unless the adapter proves it honors commandRequestId/idempotencyKey and duplicate open risk is accepted by the owner. Sync person may use retries only when the adapter is idempotent and retryDelayMs is documented.
Map the member/person access identifier before certification. The adapter may send personId directly or common identifiers such as externalRef, accessIdentifier, userId, cardId, cardNo, cardNumber, employeeCode, pin, uid, or identifier. SquareOS resolves same-brand person/client code when possible and stores unresolved values as evidence.
Test one Open gate command with fake mode off only after the vendor confirms the adapter endpoint and permissions. Capture commandRequestId/idempotencyKey, provider response, retry attempts, final status, audit id, provider request id, device id, staff actor, and owner/support approver.
Test one allowed check-in/access event and one denied/rejected/blocked event. The allowed event should show accessCallbackVerification, AccessEvent id, matched person, and jamesonCheckIn CREATED only when eligibility passes. The denied or unmatched event should show jamesonCheckIn SKIPPED or FAILED and must not create a successful check-in.
If the real device is not available yet, keep the device inactive or visible as Accepted limitation/Blocked, record middleware owner, vendor ticket, endpoint plan, verifier rule, idempotency rule, and disabled-state copy, and do not train staff or mobile users to treat simulated commands as live entry.
Record official source references used for the extraction row: Matrix COSEC product/API/manual or integrator ticket, ZKTeco ZKBioTime/BioTime API or adapter handoff, Suprema BioStar X/BioStar 2 API or adapter handoff, and the SquareOS access-control command/event test evidence.

Watch out

Do not activate a gate device without an external device id, linked gym/location, callback verifier, and clear fake-mode state.
Do not accept unsigned access events in live mode. Missing callback verifier belongs in disabled-state copy or fake-mode testing, not production check-in automation.
Do not retry Open gate blindly. Duplicate retries can physically open the gate more than once unless the middleware uses SquareOS commandRequestId/idempotencyKey.
Do not copy bearer tokens, API keys, BioStar session ids, callback tokens, HMAC secrets, custom headers, or raw access event payloads into support chats, mobile screens, crash logs, analytics, screenshots, or launch notes.
Do not assume member check-in and staff attendance use the same identity mapping. Staff-attendance hardware mapping needs separate roster proof when enabled.
Do not claim COSEC, ZKTeco, or Suprema is production-ready from a generic HTTP 200 alone. Production proof needs command evidence, signed/tokenized callback evidence, mapped person, denied-event evidence, audit id, and owner/support approval.

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