Skip to content

Custom API

Transfer

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

Transfer

Holders can Send a pass to a recipient email. The recipient claims with a link or share code and opens a live pass. No AXYN account is required for guest claim.

Who this is for

Venue engineers who need the transfer contract for headless or embed. Prefer Web SDK / hosted accept UI unless you build a custom send/claim flow.

Flow (guest-friendly)

Holder opens ticket (bearer or signed-in)
        │
        ▼
Send a pass → recipient email
        │
        ▼
Recipient opens claim link or enters share code
        │
        ▼
Claim succeeds → fresh pass_bearer → live pass

On first claim, prior live pass device sessions for that ticket are cleared so the sender’s phone no longer shows a valid door code.

Auth model

ActionCredential
Guest send / resendTicket-url bearer plus confirmed Live Pass device (device_key_hash) or email step-up. Possession of /p/ is view + door, not transfer.
Guest revokeTicket-url bearer (holder recovery; no device gate)
Signed-in send / revokeBuyer JWT (tenant derived from the ticket row)
Claim / previewClaim token or share code in the path (public)
Tenant secret aloneNot enough to invent email→transfer APIs

Optional x-api-key on signed-in routes must match the ticket's organizer tenant when present (partner BFF pattern). Hosted multi-tenant buyers (e.g. axyn.events) call with JWT only; the API resolves tenant from the ticket.

Default headless handoff is guest: use the ticket-url bearer path so you do not need a buyer JWT on the ticket page.

Guest routes (ticket-url bearer)

Confirm bodies in Full API list.

MethodPath
POST/v1/ticket-url/{token}/transfer-offers
POST/v1/ticket-url/{token}/transfer-offers/revoke
POST/v1/ticket-url/{token}/transfer-offers/resend

Issue body: recipient_email, device_key_hash (64 hex), optional ttl_seconds. Unconfirmed device → 403 step_up_required with data.sid. Open the holder-email confirm URL (sid + confirm), then retry the transfer. POST /v1/ticket-url/{token}/live-qr/confirm-step-up requires the emailed HMAC confirm; the 403 sid plus bearer is not enough. Response includes token (raw claim credential, once on create), share_code, expires_at, email_sent. Resend requires share_code and device_key_hash. Revoke stays bearer-only (no device gate).

Signed-in holder routes

MethodPath
POST/v1/tickets/{ticketId}/transfer-offers
POST/v1/tickets/{ticketId}/transfer-offers/revoke
GET/v1/me/ticket-transfer-offers

Same issue fields as the guest path (recipient_email, optional ttl_seconds). Revoke takes optional reason (no separate offer id). Call these with a buyer JWT from your server/BFF (or browser via an allowlisted BFF). Tenant is derived from the ticket; if you also send x-api-key, it must match that tenant.

Claim routes (public)

MethodPath
GET/v1/ticket-transfer-claims/{tokenOrShareCode}
POST/v1/ticket-transfer-claims/{tokenOrShareCode}

Preview is brand + event shell for the accept page. Claim may accept optional guest_first_name / guest_last_name for pass display. The claim credential is single-use; replay receives the same opaque 404 as an invalid or expired link.

When the preview returns attendee_name_required: true, the ticket needs the new holder's name: the event requires a name for every ticket, or the buyer named this ticket's holder at checkout (Agent default pending ENG-733 Q-7). Send both names on the claim. A claim without them is refused with HTTP 400 attendee_name_required and nothing is claimed. A name sent on any claim replaces both parts of the previous holder's name (Agent default pending ENG-733 Q-8). See Attendee details.

Success includes pass_bearer. Open the recipient live pass with that bearer (hosted /tickets/{pass_bearer} or SDK BearerTicketScreen). Do not treat any legacy qr_code field in the claim body as a forever door barcode.

Hosted accept UI lives under AXYN web (/transfer/accept/…). Embed partners may deep-link to their own claim UI that calls the same public APIs.

Do / do not

Do

  • Treat claim tokens and share codes as secrets (HTTPS only; do not log full values).
  • Consume each claim credential once and retain the emailed Live Pass link for recovery.
  • Expect opaque 404s for bad or used credentials (enumeration-safe).
  • After claim, send the recipient to the live pass, not a static barcode.

Do not

  • Build “list all transfers for any email” with the secret API key.
  • Assume the raw claim token is returned on every idempotent issue replay (it is returned once on create).
  • Keep showing the sender’s live pass after a successful first claim.
  • Invent claim fields that are not in OpenAPI.
PageRole
Live passRotating door code + step-up
UpgradePay the difference; same URL
Ticket deliveryBuy vs see; email
Headless APICheckout architecture
Full API listMachine contract

Next