Skip to content

Authentication and API keys

Authenticate to the ShowTix Partner API with organisation-scoped bearer keys — scopes, live and test keys, IP allowlists, rolling and revoking.

For developersLast updated

On this page

Every request is authenticated with an API key sent as a bearer token. Keys belong to one organisation: responses only ever contain that organisation's data — the events created under it, and their orders, attendees and check-ins — even when someone organises events for several organisations.

curl https://api.showtix-nonprod.link/events \
  -H "Authorization: Bearer stx_live_..."

API keys#

Organisation owners and admins create keys in Developers → API keys → Create key (step-by-step in the dashboard guide). A key looks like stx_live_ or stx_test_ followed by 32 base62 characters. The full secret is shown once, at creation; afterwards the dashboard shows only its prefix and last four characters (e.g. stx_live_Ab3dE9x…k2Pq).

ShowTix can also issue a key for your organisation on request — it appears in your list with an Issued by ShowTix badge and works the same way.

Check which key you're using — its organisation, mode and scopes — with GET /.

StatusErrorMeaning
401missing_api_keyNo Authorization: Bearer header was sent.
401invalid_api_keyThe key is malformed or doesn't exist.
401api_key_revokedThe key was revoked in the dashboard.
401api_key_expiredThe key was rolled and its grace period has ended.
403insufficient_scopeThe key is valid but lacks the scope this endpoint needs.
401 response
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided.",
    "param": null,
    "request_id": "F7xq2LmN8vRt",
    "doc_url": "https://showtix.com.au/help/partners/api-reference#errors"
  }
}

Scopes#

Give each key only the scopes its integration needs — the dashboard calls them Permissions. Every key needs at least one. A request to an endpoint outside the key's scopes fails with 403 insufficient_scope.

ScopeGrantsEndpoints
events:readRead events, ticket types (live availability and pricing) and venues.GET /events, GET /events/{id}, GET /events/{id}/ticket_types, GET /venues, GET /venues/{id}
orders:readRead orders, tickets and checkout sessions.GET /orders, GET /orders/{id}, GET /tickets/{id}, GET /checkout_sessions/{id}
orders:writeCreate checkout sessions (holds) and issue comp tickets.POST /checkout_sessions, POST /comp_tickets
attendees:readRead attendee lists (and individual tickets).GET /events/{id}/attendees, GET /tickets/{id}
check_in:writeCheck tickets in at the door.POST /events/{id}/check_ins
webhooks:manageManage webhook endpoints through the API.GET/POST /webhook_endpoints, GET/PATCH/DELETE /webhook_endpoints/{id}, POST /webhook_endpoints/{id}/test

GET / (key info) works with any valid key, and GET /openapi.json needs no key at all.

Live and test keys#

You choose the mode when you create a key; it can't be changed later.

stx_live_stx_test_
ReadsYour organisation's real data.Your organisation's real data (read-only, safe).
WritesReal holds, real orders, real comp tickets, real check-ins.Validated in full — auth, scopes, availability, purchase limits, pricing — but a dry run: nothing is held, issued or checked in.
livemodetruefalse
dry_run (writes)falsetrue
WebhooksFired for real activity.Never fired by test-key writes. Use Send test event in the dashboard or POST /webhook_endpoints/{id}/test for sample payloads.
Default rate limit120 requests / minute60 requests / minute

A test checkout session

Test keys return "id": null and a checkout_url pointing at the public event page — so you can build and test the whole redirect flow without holding inventory.

Keeping keys secret#

  • Call the API from your server only. Keep keys in environment variables or a secrets manager — never in source control, mobile app bundles or front-end code.

  • Browser requests are blocked: requests made from a web page fail with 403 browser_request_blocked, so a key can't be used from front-end code even by mistake. To sell tickets inside a web page, use the embeddable checkout, which needs no key.

  • Use separate keys per integration and environment so you can revoke one without touching the others.

  • Think a key has leaked? Revoke it immediately and email support@showtix.com.au.

IP allowlists#

Optionally restrict a key to the addresses your servers call from. In the key's IP allowlist field, add individual IPs (203.0.113.10) or CIDR ranges (10.0.0.0/8), separated by commas, when creating or editing the key. An empty list allows any address. Requests from anywhere else fail with 403 ip_not_allowed — even with a valid key.

403 response
{
  "error": {
    "type": "permission_error",
    "code": "ip_not_allowed",
    "message": "Requests from 198.51.100.7 are not allowed for this API key.",
    "param": null,
    "request_id": "F7xq2LmN8vRt",
    "doc_url": "https://showtix.com.au/help/partners/api-reference#errors"
  }
}

Rotation & revocation#

Rolling a key#

Roll key replaces a key without downtime. You get a new secret immediately (same name, mode, permissions and allowlist), and the old key keeps working for the grace period you pick under Old key expires: Now, 1 hour, 24 hours (default), 3 days or 7 days (the API accepts 0–168 hours). During the grace period the old key shows as Expiring; afterwards it shows Expired and returns 401 api_key_expired. Choosing Now revokes the old key straight away, so it returns 401 api_key_revoked.

  1. Open Developers → API keys, open the key's actions menu and choose Roll key, then copy the new secret.

  2. Deploy the new secret to every server that uses it.

  3. Confirm traffic has moved: the old key's Last used time in Developers stops advancing.

Revoking a key#

Revoke takes effect immediately — the next request with that key fails with 401 api_key_revoked. Revocation can't be undone; create a new key instead. Rotate keys whenever someone with access to them leaves your team.

Was this article helpful?

Related articles