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
| Action | Credential |
|---|---|
| Guest send / resend | Ticket-url bearer plus confirmed Live Pass device (device_key_hash) or email step-up. Possession of /p/ is view + door, not transfer. |
| Guest revoke | Ticket-url bearer (holder recovery; no device gate) |
| Signed-in send / revoke | Buyer JWT (tenant derived from the ticket row) |
| Claim / preview | Claim token or share code in the path (public) |
| Tenant secret alone | Not 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.
| Method | Path |
|---|---|
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
| Method | Path |
|---|---|
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)
| Method | Path |
|---|---|
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
tokenis 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.
Related
| Page | Role |
|---|---|
| Live pass | Rotating door code + step-up |
| Upgrade | Pay the difference; same URL |
| Ticket delivery | Buy vs see; email |
| Headless API | Checkout architecture |
| Full API list | Machine contract |