Reference

API

Every portal is built on the same public API. Anything you can do in a portal, you can do from a script.

Basics

• Base URL: api.ticketdemo.xyz, HTTPS only.
• Format: JSON in and out. Timestamps are RFC 3339 in UTC; money is a decimal string with the order's currency alongside.
• Specification: an OpenAPI 3.1 document is the contract; the portals' client types are generated from it. Ask your platform contact for the current file.

Authentication

Staff and fan endpoints take a bearer token: the ID token issued at sign‑in (an access token is rejected). Tokens are short‑lived; refresh through the normal sign‑in flow.

GET /api/me
Authorization: Bearer <id token>

Public storefront reads (event lists, event detail, the location hint) need no token. Buyer‑flow endpoints (inventory, holds, checkout) need an admission token from the waiting room, sent in the X-Admission-Token header, in addition to sign‑in for the purchase itself.

Authorization

What a token may do is decided by the roles the account holds. A resource you may not see returns 404, not 403, so the API never confirms that something exists.

Errors

Errors are JSON with a message, and on customer‑facing endpoints a stable code the storefront uses for translation:

{ "error": "This seat is no longer available.", "code": "SEAT_UNAVAILABLE" }

Conventions worth knowing

• Paths are exact. A trailing slash, a doubled slash or a dot segment is a 404.
• Writes that must not repeat (batch scans, refunds) carry a client‑chosen id and are idempotent.
• Ticket secrets travel in request bodies, never in URLs, so they don't land in logs.
• Rate limits and bot checks are enforced at the edge; a 429 asks you to slow down.

Door scanning

Single scan: POST /api/venues/{id}/events/{eventId}/scan with { "access_token": "…" }. The value can be the raw QR content (tkts:1:<token>) or the bare token. Batched, offline‑queued scans go to …/scan/batch with a device id and a per‑scan client id.