API Reference

The API exposes three endpoints for scanner applications, served by each issuer instance. The base URL is the client deployment's iss (e.g. https://tickets.example.com).

A public discovery endpoint is also available at {iss}/.well-known/ticket-issuer.json (no authentication required). Its structure is described in the protocol specification.

The check-in and status endpoints require a Bearer token. The API key is obtained through the enrollment exchange (below). The enrollment endpoint itself does not require a Bearer; it uses the enrollment token as a credential.

Authorization: Bearer sk_live_01HXXX...long-opaque-key

• Each API key is scoped to an event (and optionally a gate).
• Keys expire at the expires_at timestamp returned during enrollment.
• An invalid, expired, or revoked key returns 401 UNAUTHORIZED.
• Keys MUST be stored in the platform's secure storage (Keychain, Keystore).

Exchanges an enrollment token (from a setup QR code) for a long-lived API key. The token is single-use: a second attempt with the same token returns INVALID_TOKEN.

curl -X POST https://tickets.example.com/api/v1/scanners/enroll \
  -H "Content-Type: application/json" \
  -d '{
    "token": "st_01HXXX...opaque-enrollment-token",
    "scanner_id": "550e8400-e29b-41d4-a716-446655440000",
    "scanner_name": "iPhone 14 - North Gate",
    "scanner_platform": "ios-18.2"
  }'

Request parameters

Response · 200 OK

{
  "api_key": "sk_live_01HXXX...long-opaque-key",
  "api_key_id": "sck_01HXXX...ULID",
  "scope": {
    "eid": "evt_01HXXX...ULID",
    "event_name": "Gala Concert",
    "event_date": "2026-06-15T20:00:00Z",
    "gate_id": "north",
    "expires_at": "2026-06-16T02:00:00Z"
  },
  "issuer": {
    "name": "Festival des Arts",
    "iss": "https://tickets.example.com"
  }
}

Enrollment errors

Marks a ticket as used. Idempotent: replaying the same request with the same idempotency_key returns the same result. A second request with the same tid but a different idempotency_key is treated as a double-scan and returns already_used.

Request

curl -X POST https://tickets.example.com/api/v1/tickets/check-in \
  -H "Authorization: Bearer sk_live_01HXXX..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "tid": "01HXXX...ULID",
    "eid": "evt_01HXXX...ULID",
    "scanned_at": "2026-06-15T19:42:13Z",
    "scanner_id": "gate-north-01",
    "gate_id": "north",
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response · 200 OK

The response is always 200 with a status field indicating the outcome. This allows scanners to distinguish between different cases without parsing HTTP status codes.

{
  "status": "valid",
  "ticket": {
    "tid": "01HXXX...ULID",
    "eid": "evt_01HXXX...ULID",
    "holder_name": "J. Smith",
    "ticket_type": "VIP",
    "checked_in_at": "2026-06-15T19:42:13Z"
  }
}

{
  "status": "already_used",
  "ticket": {
    "tid": "01HXXX...ULID",
    "eid": "evt_01HXXX...ULID",
    "holder_name": "J. Smith",
    "ticket_type": "VIP",
    "checked_in_at": "2026-06-15T19:30:00Z"
  }
}

Status values

Returns the current state of a ticket without modifying it. Useful for scanner pre-checks, admin tools, or post-event reconciliation.

curl https://tickets.example.com/api/v1/tickets/01HXXX...ULID/status \
  -H "Authorization: Bearer sk_live_01HXXX..."

{
  "tid": "01HXXX...ULID",
  "eid": "evt_01HXXX...ULID",
  "status": "valid",
  "holder_name": "J. Smith",
  "ticket_type": "VIP",
  "issued_at": "2026-05-01T10:00:00Z",
  "checked_in_at": null
}

If the tid does not exist, the issuer returns 404 NOT_FOUND.

The check-in endpoint uses an idempotency key to deduplicate retries. Generate a unique UUID v4 per scan attempt and pass it either in the body (idempotency_key) or in the HTTP header (Idempotency-Key).

All non-2xx responses use a standard error envelope:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is missing, expired, or revoked.",
    "details": {}
  }
}

Issuers MUST rate-limit each endpoint per scanner credential. When the limit is reached, the server returns 429 RATE_LIMITED with a Retry-After header indicating the number of seconds to wait.

• Enrollment endpoint: rate-limited by IP and by token to prevent brute-force.
• Check-in endpoint: rate-limited by scanner credential.
• Status endpoint: rate-limited by scanner credential.

Scanners SHOULD implement exponential backoff on 429 responses and respect the Retry-After value.