Authentication
API keys, scopes, and sandbox mode.
Every request to the Tablezio API is authenticated with a key. Keys are scoped to a single restaurant and to specific permissions.
Send the key on every request
You can pass the key in either of these headers — both are equivalent:
X-API-Key: tbz_8b2c3d…Authorization: Bearer tbz_8b2c3d…Requests without a valid key return a 401 authentication_error. Requests with a key that's missing a required scope return 403 permission_error.
Test vs. live keys
Mark a key as sandbox when you create it. Sandbox keys hit a real restaurant record but operations are flagged with livemode: false on every resource and on every webhook event. You can run end-to-end tests safely — kitchen printers and payment captures are skipped automatically for sandbox traffic.
Scopes
Scopes follow a resource:action pattern. * is the wildcard.
| Scope | Grants |
|---|---|
* | Every endpoint |
orders:read / orders:write | List, retrieve / create, update, cancel orders |
menu:read / menu:write | Items, categories, modifier groups |
reservations:read / :write | Reservations & status transitions |
customers:read / :write | Customer CRUD, blocking |
loyalty:read / :write | Loyalty rules, rewards, redemptions |
inventory:read / :write | Inventory items, stock movements |
analytics:read | Dashboards, revenue, forecasts |
reports:read / :write | Financial reports |
webhooks:read / :write | Manage webhook endpoints |
events:read | Inspect emitted events and delivery history |
Rotating keys
Compromised a key? Disable it in Settings → API; existing requests with that key will start returning 401 immediately. There's no grace period — rotate often.
Security checklist
- Store keys in your secret manager (Doppler, Vault, AWS Secrets Manager).
- Never embed live keys in mobile/web frontends.
- Use a separate sandbox key per developer machine.
- Pin your client to TLS 1.2+. The API rejects older versions.