Authentication and API Keys
Every request to the Seaty API is authenticated with an API key, sent as a bearer token. The key identifies your organisation and what the request is allowed to do.
Sending your key
Put the key in the Authorization header on every request:
Authorization: Bearer sk_live_your_key_here
Requests without a valid key receive 401 unauthorized. There is no other way to authenticate: no query-string keys, no cookies, no separate username and password.
Organisation scoping
This is the most important thing to understand: a key can only ever see the organisation it was created for. Every request is filtered to that organisation on the server. If you ask for an event, date or order id that belongs to a different organisation, the API behaves as if it does not exist (a 404), never returning another organisation's data. You do not pass an organisation id yourself; it is taken from the key.
Scopes
A key carries one or both of these scopes, decided when you create it:
| Scope | Allows |
|---|---|
read | All the read endpoints (events, dates, orders, tickets, payments, discounts, attendees, summaries). Every key has this. |
write:balance_payments | Recording external balance payments against an event. Only keys created with this permission have it. |
A read-only key that attempts a write receives 403 forbidden with a message naming the scope it is missing. Grant write:balance_payments only to keys that genuinely need to record payments.
Who can create keys
Only an organisation super-admin can create, view or revoke API keys. It is an owner-level action by design and is not a delegable staff permission. Keys are created and managed from the organisation admin Tools → API Keys area.
Keeping keys safe
- The full key is shown once, when created. Seaty stores only a SHA-256 hash, so it can never be shown again.
- Treat a key like a password. Never commit it to source control, embed it in a public website or mobile app, or paste it into a support ticket or chat.
- Store keys in a secrets manager or your platform's environment variables, not in code.
- Use separate keys for separate integrations (for example one for accounting, one for a dashboard). If one is compromised you can revoke just that one without disrupting the others, and the name tells you what each key is for.
- Keys do not expire automatically. They remain valid until you revoke them.
Revoking a key
If a key is exposed, no longer needed, or you simply want to rotate it:
- Go to Tools → API Keys in your organisation admin.
- Find the key by its name and prefix.
- Choose Revoke.
Revocation takes effect immediately and cannot be undone. Any integration still using that key will start receiving 401 unauthorized. To rotate, create a new key first, switch your integration over, then revoke the old one.
What you can see about a key
After creation, the admin list shows each key's name, its prefix (the first part, so you can tell keys apart), its scopes, when it was created, when it was last used, and whether it is active or revoked. The full secret is never shown again.
Next
- Requests and responses: the conventions that apply to every call.
- Reference: scopes, error codes and the full endpoint list.
Need help? Email support@seaty.co.uk.