/api/scan

The door scanner's three calls — sync a batch, ask what is already in, take one back.

Everything the door scanner does goes through this one path: POST to sync a batch, GET to ask what is already checked in, DELETE to take a scan back. All three take the same scanner token and answer 403 the same way, so a revoked device loses all three at once. A missing or expired session returns 401; keep queued scans and retry after the device reauthenticates.

Each request requires both the signed scanner grant and a valid session for the signed-in user who owns the target grant membership. Origin is optional for these three operations: browsers omit it on same-origin reads, and existing non-browser scanner clients may omit it. When supplied, it must exactly match a configured first-party origin. Grant revocation and live event/membership checks still apply to every operation.

POST /api/scan

Accepts scans queued on a device, possibly hours after the fact.

Ticket codes are HMAC-verified server-side before any database work, so a forged code is rejected without a query. Rows are upserted on (ticket_id, scan_key) with duplicates ignored — replaying a batch cannot double-admit a guest, which matters because a device on flaky venue wifi genuinely does not know whether its last batch landed.

Request

Prop

Type

Scan

Prop

Type

Request
curl -X POST "$XPERIENCE_ORIGIN/api/scan" \
  -H 'content-type: application/json' \
  -d '{
    "token": "<scanner grant token>",
    "scans": [{
      "code": "<signed ticket code>",
      "scanKey": "<ticket uuid>:2026-10-17",
      "scannedAt": "2026-10-17T11:04:22.000Z",
      "device": "door 2"
    }]
  }'

Response

200 OK
{
  "accepted": ["3f694bc0-1757-42cb-816f-4bb2062c47a3:2026-10-17"],
  "rejected": [],
  "checkedIn": 412
}

Prop

Type

Rejected is not an error

A rejected scan can be an invalid code or a genuine ticket whose participant no longer has admission. Keep the original scan and refusal for organiser review, remove it from pending sync, and do not count it as accepted attendance.

Status codes

CodeMeaning
200Batch processed. Check accepted and rejected, not just the status.
400Invalid scan record fields or syntactically malformed JSON.
401No valid Better Auth session for the grant's target membership; retain the queue and retry after reauthentication.
403Scanner token invalid/forged, request origin untrusted, or a well-formed non-object body that reaches the missing-token check.
404Token verified but the event no longer exists.
413More than 500 scans in one batch. The first-party client already sends 200.

Scanner protocol failures use { error: string }. An origin, JSON parser, or body limit rejected before the scanner protocol runs uses the API-wide { statusCode: number, message: string, error?: string } error envelope. The affected 400, 403, 413, and 500 response schemas admit both concrete shapes; the protocol's event-missing 404 uses { error: string }.

Input status precedence

A well-formed non-object JSON body reaches the scanner token check and returns 403. Syntactically invalid JSON is rejected by the request parser with 400. Valid object payloads use the concrete scanner schema.

Independent settlement (API 6.1.0)

Implemented locally for the next rollout. Each scan commits independently. A cancelled pass or other explicit admission refusal cannot roll back the valid scans before or after it. An older printed code remains usable when another active pass for the same participant includes entrance access. A fresh manifest contains only currently eligible participants; saved offline manifests can still become stale and cannot be remotely recalled.

The optional rejection detail is invalid-code for a bad signature or a ticket outside the grant's live event scope, and admission-denied for the database's explicit admission refusal (including closed events or no active entrance pass). reason: "forged" is retained as the legacy rejection classification so installed clients still parse responses. It does not mean every declined ticket is counterfeit.

Only acknowledge records actually sent in the request. New clients atomically retain each terminal rejection for review, remove rejected keys from the local accepted history, and preserve new scans added while sync is in flight. They show a refusal separately from accepted attendance.

A timeout, unknown database error or unavailable service returns an error and keeps the client batch queued. Earlier scans may already have committed; replay is idempotent. A 401 requires signing in again; a 403 requires the organiser to restore or replace access. Neither response authorises deleting queued work. The signed-in actor must own the grant's current membership and binding; holding another person's grant URL is insufficient.

GET /api/scan

Which tickets this door already knows are in, for one day.

Check-in state used to be per-device, so a ticket scanned at one entrance still read as new at another. A device unions this with what it recorded itself — offline it simply keeps its own answer, which is the same answer it had before this existed.

Request
curl "$XPERIENCE_ORIGIN/api/scan?token=<token>&day=2026-10-17"

day is a Kuala Lumpur date, YYYY-MM-DD, matching the tail of a scanKey.

200 OK
{ "scanKeys": ["3f694bc0-1757-42cb-816f-4bb2062c47a3:2026-10-17"] }

Status codes

CodeMeaning
200Scan keys for that event and day. Empty array if none.
400day was not YYYY-MM-DD.
401No valid Better Auth session for the grant's target membership.
403Scanner token invalid or forged.

The token is checked first here

Unlike POST, the token is read before day is validated — so a 400 from this call means your token was already accepted.

DELETE /api/scan

Takes a scan back.

A door gets mis-scans: the wrong ticket held up, two phones at once, a volunteer scanning the queue rather than the person. The row is not cosmetic — it counts toward attendance and awards points — so removing it gives the points back with it.

Request
curl -X DELETE "$XPERIENCE_ORIGIN/api/scan" \
  -H 'content-type: application/json' \
  -d '{
    "token": "<scanner grant token>",
    "code": "<signed ticket code>",
    "scanKey": "<ticket uuid>:2026-10-17"
  }'
200 OK
{ "undone": "3f694bc0-1757-42cb-816f-4bb2062c47a3:2026-10-17" }

Status codes

CodeMeaning
200Gone, or already gone. Both, deliberately — see below.
400Body was not a JSON object, or carried no usable code and scanKey.
401No valid Better Auth session for the grant's target membership; retain the queued undo and retry after reauthentication.
403Scanner token invalid or forged.
500The delete itself failed. Retry is safe.

A repeated undo is not an error

Replaying an undo matches no row and still returns 200. A device on bad wifi cannot tell whether its first attempt landed, and making the second attempt an error would only teach it to hide a real failure.

Undo is recorded

Every successful undo is written to the audit log with who took it back and who had scanned it originally. An organiser can tell a careful scanner from one undoing a fifth of their own scans, which is the point.

On this page