Access Devices

Access device endpoints live under /public/v1/access, but they are not developer Public API resources. They keep the existing gate/device validation contract and use device-key authentication instead of OAuth client credentials. 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:

x-device-key: <device_key>

The preferred header is x-device-key. Runtime also accepts the legacy aliases x-access-device-key and x-api-key for access-device requests only. Do not use those aliases for developer Public API resources. 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:

{
  "status": 200,
  "error": false,
  "message": "ACCESS_DECISION",
  "data": {
    "allowed": true,
    "reasonCode": "OK",
    "reasonMessage": "Access granted",
    "openDurationSeconds": 5
  }
}

Check device health

GET /public/v1/access/health

Returns a lightweight heartbeat when the device key is valid.

Example

curl -X GET \
  -H "x-device-key: <device_key>" \
  https://api.fitsociety.io/public/v1/access/health

Success response

{
  "status": 200,
  "error": false,
  "message": "ACCESS_HEALTH_OK",
  "data": {
    "status": "ok",
    "device": {
      "id": "66f7b8b1e13c8d25f4d3d90a",
      "locationId": "66f7b8b1e13c8d25f4d3d90b",
      "zoneKey": "front_door"
    },
    "time": "2026-07-14T12:00:00.000Z"
  }
}

Field	Type	Nullable	Description
`status`	string	no	Static heartbeat value, currently `ok`.
`device.id`	string	no	Access device ID.
`device.locationId`	string	yes	Device location ID when configured.
`device.zoneKey`	string	yes	Device zone key when configured.
`time`	string	no	Server UTC timestamp in ISO 8601 format.

Auth errors

Status	Message
`401`	`DEVICE_NOT_AUTHORIZED`

Validate access

POST /public/v1/access/validate

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

curl -X POST \
  -H "x-device-key: <device_key>" \
  -H "Content-Type: application/json" \
  -d '{"qrToken":"<signed_qr_token>"}' \
  https://api.fitsociety.io/public/v1/access/validate

Field	Type	Required	Description
`qrToken`	string	yes	Signed QR token generated by the client access flow.

QR retries are idempotent through the QR session ID embedded in the signed token.

Partner credential request

curl -X POST \
  -H "x-device-key: <device_key>" \
  -H "Content-Type: application/json" \
  -d '{"credentialType":"badgeUid","credentialValue":"04AABBCCDD","scanId":"partner-scan-123"}' \
  https://api.fitsociety.io/public/v1/access/validate

Field	Type	Required	Description
`credentialType`	string	yes	Credential type. Current public credential flow supports `badgeUid`.
`credentialValue`	string	yes	Raw credential value from the scanner. The API normalizes supported values before lookup.
`scanId`	string	yes	Stable idempotency key for this physical scan. Reuse the same value when retrying the same scan.

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.

{
  "status": 200,
  "error": false,
  "message": "ACCESS_DECISION",
  "data": {
    "allowed": false,
    "reasonCode": "OUTSIDE_ALLOWED_HOURS",
    "reasonMessage": "Access is outside the allowed hours"
  }
}

When access is granted, openDurationSeconds may be included:

{
  "status": 200,
  "error": false,
  "message": "ACCESS_DECISION",
  "data": {
    "allowed": true,
    "reasonCode": "OK",
    "reasonMessage": "Access granted",
    "openDurationSeconds": 5
  }
}

Decision fields

Field	Type	Nullable	Description
`allowed`	boolean	no	Whether the device should open access.
`reasonCode`	string	no	Stable decision code. Treat unknown values as denied.
`reasonMessage`	string	no	Human-readable reason. Do not parse for business logic.
`openDurationSeconds`	number	yes	Suggested opening duration when access is allowed and the device has a duration configured.

Decision codes

Reason code	Meaning
`OK`	Access is allowed.
`QR_INVALID`	QR token is missing, malformed, or fails signature validation.
`QR_EXPIRED`	QR token has expired.
`RATE_LIMITED`	Device exceeded the access validation rate limit.
`CLIENT_NOT_FOUND`	Client could not be resolved.
`CLIENT_NOT_IN_COMPANY`	Client does not belong to the device company.
`NO_ACTIVE_PRODUCT`	Client has no active access-entitling product.
`PRODUCT_ACCESS_DISABLED`	Product exists but access entitlement is disabled.
`LOCATION_NOT_ALLOWED`	Client/product is not allowed for the device location.
`ZONE_NOT_ALLOWED`	Client/product is not allowed for the device zone.
`PAYMENT_BLOCKED`	Access is blocked because of payment state.
`OUTSIDE_ALLOWED_HOURS`	Scan is outside configured access hours.
`CREDITS_REQUIRED_NO_BALANCE`	Credits are required but no usable balance exists.
`LIMIT_REACHED_DAY`	Day access limit reached.
`LIMIT_REACHED_WEEK`	Week access limit reached.
`LIMIT_REACHED_MONTH`	Month access limit reached.
`LESSON_REQUIRED_NO_BOOKING`	A lesson booking is required but not found.
`LESSON_TOO_EARLY`	Scan is before the allowed lesson access window.
`LESSON_TOO_LATE`	Scan is after the allowed lesson access window.
`LESSON_NOT_IN_WHITELIST`	Booking exists but is not for an allowed lesson.
`CREDENTIAL_METHOD_DISABLED`	Partner credential method is disabled for the company.
`CREDENTIAL_NOT_FOUND`	Partner credential was not found.
`CREDENTIAL_INACTIVE`	Partner credential exists but is inactive.
`INTERNAL_ERROR`	Access could not be resolved safely. Treat as denied.

Validation errors

Malformed credential requests return client errors:

Status	Message	Cause
`400`	`INVALID_CREDENTIAL_TYPE`	`credentialType` is unsupported.
`400`	`CREDENTIAL_VALUE_REQUIRED`	`credentialValue` is missing or normalizes to an empty value.
`400`	`SCAN_ID_REQUIRED`	Partner credential scan has no stable `scanId`.
`401`	`DEVICE_NOT_AUTHORIZED`	Device key is missing, malformed, inactive, or company mismatched.

Client and auth errors use the application error envelope:

{
  "status": 400,
  "error": true,
  "message": "SCAN_ID_REQUIRED"
}

Rate limit

Access validation is rate limited per access device.

Setting	Default	Environment variable
Window	`1000ms`	`ACCESS_VALIDATE_RATE_WINDOW_MS`
Requests per window	`30`	`ACCESS_VALIDATE_RATE_LIMIT`

When the rate limit is exceeded, the endpoint still returns HTTP 200 with a denied access decision:

{
  "status": 200,
  "error": false,
  "message": "ACCESS_DECISION",
  "data": {
    "allowed": false,
    "reasonCode": "RATE_LIMITED",
    "reasonMessage": "Too many requests"
  }
}

Security notes

Store device keys as secrets on the edge device.
Prefer x-device-key; legacy aliases are accepted only for compatibility.
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.

Start here

Public API guides

Access Devices

Authentication

Response envelope

Check device health

Example

Success response

Auth errors

Validate access

QR request

Partner credential request

Decision response

Decision fields

Decision codes

Validation errors

Rate limit

Security notes

​Authentication

​Response envelope

​Check device health

​Example

​Success response

​Auth errors

​Validate access

​QR request

​Partner credential request

​Decision response

​Decision fields

​Decision codes

​Validation errors

​Rate limit

​Security notes

Authentication

Response envelope

Check device health

Example

Success response

Auth errors

Validate access

QR request

Partner credential request

Decision response

Decision fields

Decision codes

Validation errors

Rate limit

Security notes