Authentication
How API keys authenticate every SeatBuilder REST call — public vs secret keys, the X-Api-Key header, environments, and workspace scope.
Authentication
Every request to the public SeatBuilder REST API authenticates with a single
header: X-Api-Key. Keys are workspace-scoped and bound to a single
environment (production or sandbox). There is no OAuth, no session
cookie, and no JWT for API consumers — those flows are reserved for the
dashboard UI.
API key types
Each workspace issues two key pairs per environment:
| Prefix | Purpose | Where it lives |
|---|---|---|
pk_live_* | Publishable — safe to embed in browser code | SDK publicKey option |
sk_live_* | Secret — server-side only | Backend env var (SEATS_API_KEY) |
pk_test_* | Publishable, sandbox environment | SDK publicKey during testing |
sk_test_* | Secret, sandbox environment | Backend env var during testing |
Publishable (pk_*) keys can call the SDK runtime routes — GET event,
hold, book, release, status — and nothing else. Use them in
browser code where the key value is visible to the buyer. Secret
(sk_*) keys can call every public endpoint, including chart creation
and webhook management. Never ship sk_* keys to a browser.
The X-Api-Key header
Pass your key in the X-Api-Key request header. The server hashes the
key on receipt and looks it up in the workspace's key table.
curl -H "X-Api-Key: sk_live_xxx" \
https://api.your-host.example/api/v1/chartsCalls with a missing or malformed key return 401 Unauthorized. Calls
with a syntactically valid key whose hash isn't on file return
401 Unauthorized as well — the server does not distinguish unknown
keys from forged keys to keep enumeration noisy. See
Error model for the full error envelope.
Environments
Each workspace has two isolated environments: production and
sandbox. Keys cannot cross environments. A pk_test_* key cannot read
production events, and a pk_live_* key cannot reach sandbox data.
In practice this means:
- Develop and test against
*_test_*keys hitting your sandbox environment. - Promote to
*_live_*only when your integration is verified — the sandbox is rate-limited and may be reset.
Workspace scope
Keys are bound to one workspace. Every authenticated request
auto-scopes to that workspace's data — charts, events, webhooks, and
seat state are all isolated. There is no API surface for reading data
across workspaces; misconfigured cross-workspace requests return
403 Forbidden.
This is the only safe assumption a multi-tenant integration can make: if a buyer presents a hold token from another workspace's event, the book request rejects with 403 before any state mutation runs.