Start here
Authentication
Reference only. Not a decision unless cited in product/DECISIONS.md.
Authentication
Install two credentials. Everything else is a runtime token or a door device secret. Full table: Credentials.
Who this is for
Engineers wiring server or door clients to /v1.
What you install
| Credential | Env / header | Use |
|---|---|---|
| Secret API key | x-api-key: axyn_sk_… (AXYN_API_KEY) | Server catalog and documented server integrations |
| Publishable checkout key | AXYN_PUBLISHABLE_KEY | Browser/BFF Auth client that mints buyer JWTs |
First-party apps load the same publishable credential as
NEXT_PUBLIC_AXYN_SUPABASE_ANON_KEY (Supabase anon key for the AXYN Auth
project). Partner docs use AXYN_PUBLISHABLE_KEY; both names are the same
install value.
Production defaults (not install keys): API https://api.axyn.events, Auth
https://auth.axyn.events.
Runtime tokens (not env installs)
| Token | Header | How you get it |
|---|---|---|
| Buyer JWT | Authorization: Bearer … | signInAnonymously() (or magic link / OAuth) with Auth URL + publishable key |
| Staff JWT | Authorization: Bearer … | Staff sign-in on AXYN Auth |
| Scanner token | x-scanner-token: scn_… | Staff mint via POST /v1/tickets/scanner-tokens, or volunteer redeem of the event 6-digit join code (POST /v1/tickets/scanner-join-codes/redeem) |
Volunteer redeem is public and guess-capped: 10 attempts per IP per minute and 30 per 15 minutes, shared across API replicas, plus 40 devices per active code. Do not treat the 6-digit PIN as a long-lived secret; rotate it after the door.
Organizers assign joined scanners to lanes with
GET /v1/tickets/scanner-roster and
PATCH /v1/tickets/scanner-tokens/{tokenId}/lane (staff JWT). The volunteer
device reads assigned_lane_id from GET /v1/tickets/scanner-tokens/me
(40 calls per token per minute).
Tenant identity comes from the API key lookup on the server. Never send
tenant_id from the client as the source of truth.
Buyer JWT
Checkout routes (POST /v1/orders/preview-total, POST /v1/orders,
payments, verify, seat hold) need a buyer JWT. Mint it in your app:
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');
}
// use data.session.access_token as Authorization: Bearer …
Do not commit JWTs. Do not ask AXYN ops for a static buyer JWT as the primary path. API keys are minted in Admin -> Settings -> Developer (Credentials) — that is key provisioning, not JWT minting.
API key scopes
A key you mint in Admin can carry only these scopes:
catalog:readorders:readorders:writetickets:read
AXYN can also grant these (ask AXYN ops; you cannot mint them yourself):
catalog:writediscovery:readscan:writeclient_ip:attest(see Calling for your buyers from your server)*(wildcard; cannot mix with other scopes)
Catalog reads need catalog:read. Order create / pay / verify use the
buyer JWT (bearerAuth), not orders:write on the browser. Keep
orders:write for server integrations that are documented to use the key.
The raw secret is shown once on create or rotate — store it in your secret manager and never commit it.
Do not treat optional x-tenant-id as authority. Tenant for API-key routes
comes from the key lookup. Never send tenant_id in JSON bodies as the
source of truth.
Server proxy pattern
Browser → Auth (publishable key) → buyer JWT
Browser → your backend → AXYN (x-api-key) // catalog
Browser → AXYN (buyer JWT only, never the secret key) // checkout
Calling for your buyers from your server
AXYN limits order create, payment start and partner token exchange per client IP, so a script cannot hold inventory or test cards by cycling sessions. The limits are sized for a household or office behind one IP (60 order creates per event per minute, 60 payment starts per minute, 60 token exchanges per 15 minutes).
If your server makes those calls for your buyers (it proxies checkout, or
exchanges your user's token for an AXYN buyer session), every buyer arrives
from your server's one egress IP. Without more, your 61st buyer in a minute
gets 429.
Name the buyer instead. On each such call, send your secret API key and the buyer's IP:
POST /v1/auth/federation/token-exchange
x-api-key: axyn_sk_live_…
X-Axyn-Client-IP: 198.51.100.23
- AXYN honors
X-Axyn-Client-IPonly on a request whosex-api-keyholds theclient_ip:attestscope. Without it the header is ignored and the call counts against your server's IP. Sending it is always safe. - AXYN grants
client_ip:attest; you cannot mint it yourself. Ask AXYN ops to add it to your server key. - Send the IP your own edge saw for that buyer, resolved by your own proxy rules. Never pass on a value your caller sent you, and never send your load balancer's or your server's own address: every buyer would share one limit again.
- Each buyer then has their own limit, the same as a buyer who calls AXYN directly. AXYN can remove the scope from a key that sends invented IPs.
- The key stays on your server; a browser or app never sends
X-Axyn-Client-IP.
Scanner token
Opaque device token for scan, validate, manifest, and sync routes. Do not use it for checkout or catalog writes.
Common mistakes
- Embedding
axyn_sk_...in a SPA. - Treating Auth URL / API URL as required “keys” for production.
- Asking ops for a static buyer JWT instead of
signInAnonymously. - Mixing
*with other scopes. - Using a scanner token for order create.
- Trusting a client-supplied
tenant_id. - Proxying buyer calls from your server without
X-Axyn-Client-IP, or forwarding a caller-sent one.
Next
- Credentials
- Get started — headless happy path
- Headless API
- Web SDK
- Errors
- Testing