Skip to content

Custom API

Get started

Reference only. Not a decision unless cited in product/DECISIONS.md.

Get started

Sell a ticket through the AXYN headless API in about fifteen minutes.

Prefer Web SDK embed if you have a React site and do not need a fully custom UI. This page is the API path.

Who this is for

You run events under one AXYN tenant (an independent venue or producer). You call catalog routes from your server with a secret API key, and checkout routes with a buyer JWT minted in your app.

What you install (test key first)

EnvKindWhere
AXYN_API_KEYSecret (axyn_sk_test_... for sandbox, axyn_sk_live_... for live)Server only
AXYN_PUBLISHABLE_KEYPublishableBrowser / BFF OK

Production hosts are defaults — you do not paste them as keys:

ResourceDefault
API URLhttps://api.axyn.events
Auth URLhttps://auth.axyn.events

Also need an EVENT_ID (and tier / venue ids from catalog). List your own tenant's events with GET /v1/events (catalog:read; limit default 50, max 200, and offset). It never lists another organizer's events.

Start with a test key minted from Admin -> Settings -> Developer. Sandbox uses the production API host with an axyn_sk_test_... key, not a separate sandbox URL. Swap to an axyn_sk_live_... key only after live-key access is enabled for your organization. Full contract: Credentials.

Never put the secret API key in a browser bundle. Never install the service role on a partner site.

LayerCredentialHost default
Your serverAXYN_API_KEY → x-api-keyhttps://api.axyn.events
Browser / BFFAXYN_PUBLISHABLE_KEY → Auth clienthttps://auth.axyn.events
Browser / BFFBuyer JWT (runtime) → Authorizationsame API host

Confirm every path and body against https://api.axyn.events/openapi.json before you ship.

Bootstrap: mint a buyer JWT

Checkout needs a buyer JWT. Mint it in your app with the publishable key — do not ask ops for a static JWT. Anonymous sign-in must be enabled on the AXYN Auth project (it is on production).

import { createClient } from '@supabase/supabase-js';

const auth = createClient(
  process.env.AXYN_AUTH_URL ?? 'https://auth.axyn.events',
  process.env.AXYN_PUBLISHABLE_KEY!
);

const { data, error } = await auth.auth.signInAnonymously();
if (error || !data.session?.access_token) {
  throw error ?? new Error('No buyer session');
}
const BUYER_JWT = data.session.access_token;

Sandbox uses the default Auth URL. Internal local work may override hosts, but external partner sandbox testing should not.

Steps

Set AXYN_API_URL only when not using the production default (https://api.axyn.events). Examples below use that default.

1. Load event detail

curl -sS "https://api.axyn.events/v1/events/$EVENT_ID" \
  -H "x-api-key: $AXYN_API_KEY"

EVENT_ID is the buyer-flow id (source_venue_event_id) with fallback lookup by owned event.id. Response envelope: { "success": true, "data": … }.

If data.who_it_is_for is present, show it as Who it is for. If a series show row has who_it_is_for_override, show that on that show only (that night is for different guests). Hide the heading when the value is empty. This string is listing copy. It is not a door ID check. Do not fail checkout on it.

2. Read tiers for the event

curl -sS "https://api.axyn.events/v1/events/$EVENT_ID/tiers" \
  -H "x-api-key: $AXYN_API_KEY"

Pick a ticket_tier_id from data.ticket_tiers. Each tier includes venue_id — use that (and the same EVENT_ID as venue_event_id) on order create.

3. Preview the all-in total

curl -sS -X POST "https://api.axyn.events/v1/orders/preview-total" \
  -H "Authorization: Bearer $BUYER_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "venue_id": "'"$VENUE_ID"'",
    "venue_event_id": "'"$EVENT_ID"'",
    "payment_method": "card",
    "lines": [
      {
        "item_type": "ticket",
        "ticket_tier_id": "'"$TIER_ID"'",
        "quantity": 1
      }
    ]
  }'

Show the buyer the returned all-in before you create the order.

4. Create an order

Order create requires the buyer JWT and an Idempotency-Key. Do not send tenant_id in the body.

curl -sS -X POST "https://api.axyn.events/v1/orders" \
  -H "Authorization: Bearer $BUYER_JWT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "venue_id": "'"$VENUE_ID"'",
    "venue_event_id": "'"$EVENT_ID"'",
    "payment_method": "card",
    "lines": [
      {
        "item_type": "ticket",
        "ticket_tier_id": "'"$TIER_ID"'",
        "quantity": 1
      }
    ],
    "purchaser_email": "buyer@example.com",
    "purchaser_name": "Sandbox Buyer"
  }'

Required body fields today: venue_id, venue_event_id, payment_method, lines[] with item_type + quantity (and ticket_tier_id when item_type is ticket). See OpenAPI OrderLineInput / PaymentMethod.

When event detail returns attendee_details_mode: "required", also send attendees with a first and last name for every ticket. An email per ticket is optional. See Attendee details.

If you are not ready for headless buyer auth, use hosted checkout or the embed spine instead (Choose an integration).

5. Start payment

curl -sS -X POST "https://api.axyn.events/v1/orders/$ORDER_ID/payments/start" \
  -H "Authorization: Bearer $BUYER_JWT" \
  -H "Idempotency-Key: $(uuidgen)"

Complete the Stripe PaymentIntent with the returned client secret. When the order uses an axyn_sk_test_... key, use Stripe test cards such as 4242 4242 4242 4242. Do not create your own PaymentIntent outside AXYN.

Wallets the organizer allows. Preview-total, payment start (payment.wallets) and event detail return wallets: apple_pay, google_pay and link, each auto or never. The organizer sets them on Settings › Payments ("How buyers can pay"). Pass them to your Stripe Payment Element as its wallets option:

elements.create('payment', {
  wallets: {
    applePay: wallets.apple_pay,
    googlePay: wallets.google_pay,
    link: wallets.link,
  },
});

AXYN cannot apply this on your page, so your payment form must. Cards are always accepted. Apple Pay and Google Pay show on your site once a buyer has started checkout there with your API key: AXYN registers your site on the organizer's payment account after that first checkout.

6. Verify and hand off the guest (no AXYN login)

curl -sS -X POST "https://api.axyn.events/v1/orders/$ORDER_ID/verify-payment" \
  -H "Authorization: Bearer $BUYER_JWT"

The buyer stays a completely anonymous guest. Do not send them to an AXYN sign-in wall. After pay:

  1. Same browser session — GET /v1/me/tickets with the anonymous buyer JWT you already minted (confirmation / “your tickets” on your site).
  2. Email recovery — AXYN enqueues a venue-named email with a hosted bearer link (/tickets/{token}). That page is the white-label see-ticket surface for other devices; no account required.
  3. Do not invent email→ticket lookup, partner-owned login, or a public “re-fetch raw bearer later” API.
curl -sS "https://api.axyn.events/v1/me/tickets" \
  -H "Authorization: Bearer $BUYER_JWT"

Treat confirmation as order + open pass, not “save this barcode forever.” Day-of admission is the live pass on the hosted (or embed) ticket page — not a screenshot of a buy-time barcode. Extra devices may need email step-up; holders can Send a pass. Details: Ticket delivery, Live pass, Transfer.

7. Scan at the door

Door apps do not use the tenant API key. Two OpenAPI paths:

Device token (scanner app):

curl -sS -X POST "https://api.axyn.events/v1/tickets/validate" \
  -H "x-scanner-token: $SCANNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_code": "'"$QR_CODE"'",
    "venue_event_id": "'"$EVENT_ID"'"
  }'

Staff JWT (staff/admin online scan):

curl -sS -X POST "https://api.axyn.events/v1/tickets/scan" \
  -H "Authorization: Bearer $STAFF_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "qr_code": "'"$QR_CODE"'"
  }'

Scan outcomes return HTTP 200 with data.result_code for business results (admit / already scanned / invalid). Only transport and auth failures use 4xx/5xx. See Errors.

Staff mint device tokens via POST /v1/tickets/scanner-tokens (staff JWT; raw token shown once). Door volunteers can redeem a per-event 6-digit join code instead (POST /v1/tickets/scanner-join-codes/redeem) and then set their name with PATCH /v1/tickets/scanner-tokens/me. Redeem allows 10 guesses per IP per minute. Organizers list the joined team with GET /v1/tickets/scanner-roster and assign lanes with PATCH /v1/tickets/scanner-tokens/{tokenId}/lane. Confirm the body in OpenAPI.

What success looks like

  • Paid order via anonymous buyer JWT (no AXYN account).
  • Same-session tickets on GET /v1/me/tickets or a working hosted /tickets/{token} link from the venue-named email.
  • Guest never forced through AXYN login to see their ticket.
  • Door scan returns an admit-class result_code (scanner token / staff JWT).

Details: Ticket delivery.

Security

  • Secret API key: server / secret manager only — never browsers or mobile apps.
  • Do not log keys, JWTs, or scanner tokens.
  • Do not send tenant_id as authority; tenant comes from the API key.
  • Do not probe other tenants’ ids — misses are enumeration-safe 404s.
  • Door join-code redeem is public; the API caps guesses per IP (see OpenAPI).

Common mistakes

  • Expecting GET /v1/events to list every organizer's events. It lists only the events of the tenant that owns your API key.
  • Asking ops for a static buyer JWT — mint via signInAnonymously.
  • Forcing AXYN login after pay — guests are anonymous; use JWT session + hosted bearer email.
  • Pasting API/Auth URLs as required “keys” for production — use defaults.
  • Setting AXYN_API_URL to https://sandbox.api.axyn.events: sandbox uses https://api.axyn.events with an axyn_sk_test_... key.
  • Sending event_id / tier_id instead of venue_event_id / ticket_tier_id on order create.
  • Sending tenant_id in the body. Tenant comes from credentials, not the client body.
  • Skipping Idempotency-Key on order create.
  • Putting axyn_sk_... in frontend code.
  • Using the tenant API key for door scan.
  • Inventing request fields that are not in OpenAPI.
  • Promising stakeholders that MVP email From is @yourvenue.com — it is not; see Ticket delivery.
  • Promising “Add to Wallet at buy = door-ready forever” — wallet and door admit stay aligned with the live pass; see Ticket delivery.

Next