Build on the OS
Read your events and tickets from your own systems, and get told when something happens. A sandbox key in a minute, webhooks that are signed and replay-safe.
Sandbox first
A tr_test_ key reads fixture data and touches nothing real — including a sold-out tier, a refunded ticket and a redeemed one, which a fresh live account has none of. Live and test are different keys rather than a header, so a request cannot reach real data by leaving something out.
Signed webhooks
HMAC-SHA256 over timestamp.body with your endpoint’s own secret, in a TicketRoyality-Signature header. Reject anything older than five minutes, or a captured payload can be replayed forever. Failures retry with an increasing delay and stay in your delivery log either way.
Scoped keys
A key carries only the scopes you give it. Attendee names and emails sit behind attendees:read, so a reporting key can count tickets without ever being able to export a mailing list.
Read-only, and honest about it
Everything is under /api/v1 and every endpoint is a GET. There is no write API yet — no creating events, no placing orders, no scanning through the API — and no SDKs. When those exist they will be on this page and not before.
Core endpoints
All paths are prefixed with /api/v1. Your API key in the Authorization: Bearer header. Create one under Developers in your organiser dashboard.
| Method | Path | Auth | Notes |
|---|---|---|---|
| GET | /events | events:read | Your own events, with tier prices and how many are sold. |
| GET | /tickets | tickets:read | Filter with ?event_id= and ?limit=. Names and emails need attendees:read too. |
Webhook events
| Event type | Payload |
|---|---|
| order.completed | event_id, tier_id, quantity, amount_minor, currency |
| ticket.redeemed | reference, event_id, tier_name, seat |
| ticket.refunded | reference, event_id |
| donation.received | amount_minor, currency, event_id |
The webhook is a notification, not the source of truth. If you miss one, re-read the resource — never treat a missing webhook as a missing event.
Verifying a signature
Split the header on commas into t and v1. Compute HMAC-SHA256 of `${t}.${rawBody}` with your endpoint secret and compare it to v1 in constant time. Reject anything where t is more than five minutes old.
Not built yet
No write endpoints, no SDKs, no OpenAPI file, no published rate limits and no cursor pagination — /tickets takes a limit and tops out at 500. Ask for what you need and it goes on the list.