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 uses two kinds of key per environment:

How keys are provisioned differs by type. Your publishable (pk_live_* and pk_test_*) keys are seeded automatically when the workspace is created and are usable immediately — the value you see on the dashboard API keys page is the full key, so you can copy it straight into your SDK publicKey option.

Secret (sk_live_* and sk_test_*) keys are not created automatically. Create each secret key on demand from the dashboard API keys page, where its plaintext value is shown exactly once at creation time. Copy it into your backend secret store right away — the value is never displayed again. If you lose a secret key, rotate it from the same page to mint a replacement (the old value stops working immediately). Create your secret key before you need it server-side.

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://seatbuilder.org/api/v1/charts

Calls 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.