Skip to content

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

CredentialEnv / headerUse
Secret API keyx-api-key: axyn_sk_… (AXYN_API_KEY)Server catalog and documented server integrations
Publishable checkout keyAXYN_PUBLISHABLE_KEYBrowser/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)

TokenHeaderHow you get it
Buyer JWTAuthorization: Bearer …signInAnonymously() (or magic link / OAuth) with Auth URL + publishable key
Staff JWTAuthorization: Bearer …Staff sign-in on AXYN Auth
Scanner tokenx-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:read
  • orders:read
  • orders:write
  • tickets:read

AXYN can also grant these (ask AXYN ops; you cannot mint them yourself):

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-IP only on a request whose x-api-key holds the client_ip:attest scope. 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