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)
| Env | Kind | Where |
|---|---|---|
AXYN_API_KEY | Secret (axyn_sk_test_... for sandbox, axyn_sk_live_... for live) | Server only |
AXYN_PUBLISHABLE_KEY | Publishable | Browser / BFF OK |
Production hosts are defaults — you do not paste them as keys:
| Resource | Default |
|---|---|
| API URL | https://api.axyn.events |
| Auth URL | https://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.
| Layer | Credential | Host default |
|---|---|---|
| Your server | AXYN_API_KEY → x-api-key | https://api.axyn.events |
| Browser / BFF | AXYN_PUBLISHABLE_KEY → Auth client | https://auth.axyn.events |
| Browser / BFF | Buyer JWT (runtime) → Authorization | same 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:
- Same browser session —
GET /v1/me/ticketswith the anonymous buyer JWT you already minted (confirmation / “your tickets” on your site). - 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. - 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/ticketsor 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_idas 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/eventsto 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_URLtohttps://sandbox.api.axyn.events: sandbox useshttps://api.axyn.eventswith anaxyn_sk_test_...key. - Sending
event_id/tier_idinstead ofvenue_event_id/ticket_tier_idon order create. - Sending
tenant_idin the body. Tenant comes from credentials, not the client body. - Skipping
Idempotency-Keyon 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
- Credentials — two-key contract
- Ticket delivery — buy vs see-ticket matrix
- Live pass — rotating door code + step-up
- Transfer — Send a pass / claim
- Headless API — architecture and reserved-seat notes
- Authentication
- Testing
- Web SDK — if you want embed instead
- API reference