Skip to main content
Access device endpoints use /public/v1/access with device-key authentication. Use these endpoints for turnstiles, door controllers, badge scanners, and other edge devices that need an immediate allow/deny decision.
Do not use Public API OAuth client credentials or Authorization: Bearer fspt_... access tokens for access devices. Use x-device-key for /public/v1/access/*.

Authentication

Every access-device request must include a device key:
Use x-device-key. The aliases x-access-device-key and x-api-key are also accepted for access-device requests only. Device keys must be hex strings with at least 32 characters. Missing, malformed, inactive, or unknown device keys return 401 DEVICE_NOT_AUTHORIZED. The company context is resolved from the configured access device. Use the device key for /public/v1/access/*; Public API OAuth tokens are for developer API resources.

Response envelope

Access-device endpoints use the FITsociety application envelope, not the developer Public API { data, meta } envelope:

Check device health

Returns a lightweight heartbeat when the device key is valid.

Example

Success response

Auth errors

Validate access

Evaluates a QR token or partner credential and returns an allow/deny decision. Send exactly one of these request shapes:
  • QR validation: qrToken
  • Partner credential validation: credentialType, credentialValue, scanId
If qrToken is present, the request is treated as QR validation.

QR request

Each signed QR authorizes at most one scan. Duplicate scans and replays return QR_ALREADY_USED. After an uncertain response, the member must refresh the QR. Booking entry limits still apply. Badge retries use the same scanId. Open the relay only when data.allowed is true. An HTTP 200 response alone does not authorize entry. Concurrent badge retries still being processed may return BOOKING_ADMISSION_PENDING with allowed = false. Keep the relay closed and retry the same scanId; after completion the original decision is returned. Booking-required access checks the QR’s booking occurrence, product, location, and validity window. Cancellation or rescheduling can invalidate access. Another product cannot override a rejection. A QR without booking-specific authorization returns QR_BOOKING_SCOPE_REQUIRED for booking-required access. Member QR responses include accessStatus, canShowQrCode, booking identity, and UTC accessValidFrom/accessValidUntil. Unavailable rows have an empty token. Tokens expire by the exclusive access cutoff. Products can configure lessonRules.windowEnd as lessonStart or lessonEnd and a positive maxEntriesPerBooking limit. Without these settings, windows use the lesson start and re-entry is unlimited (maxEntriesPerBooking = 0). Entry limits apply per member, booking, and location across products and zones. Refreshing the QR does not reset them. These decisions apply to online validation.

Partner credential request

Partner credential scans are gated by the company access-control credential method settings. If the credential method is disabled, the endpoint returns an access decision with allowed=false.

Decision response

Access decisions return HTTP 200 even when access is denied. Read data.allowed and data.reasonCode.
When access is granted, openDurationSeconds may be included:

Decision fields

Decision codes

Validation errors

Malformed credential requests return client errors: Client and auth errors use the application error envelope:

Rate limit

Access validation is rate limited per access device. When the rate limit is exceeded, the endpoint still returns HTTP 200 with a denied access decision:

Security notes

  • Store device keys as secrets on the edge device.
  • Use x-device-key for access-device authentication.
  • Do not log full QR tokens, credential values, device keys, or OAuth tokens.
  • Use a stable scanId for partner credential retries to prevent duplicate physical scan processing.
  • Treat any unknown reasonCode as denied.