/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.
Authentication
Every access-device request must include a device key: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
Example
Success response
Auth errors
Validate access
- QR validation:
qrToken - Partner credential validation:
credentialType,credentialValue,scanId
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 HTTP200 even when access is denied. Read
data.allowed and data.reasonCode.
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-keyfor access-device authentication. - Do not log full QR tokens, credential values, device keys, or OAuth tokens.
- Use a stable
scanIdfor partner credential retries to prevent duplicate physical scan processing. - Treat any unknown
reasonCodeas denied.