Authentication
API keys, scopes and plans, test and live keys, and rolling a key without downtime.
Every request carries a key or an OAuth access token as a bearer token:
GET /public/v1/venues/7/bookings HTTP/1.1
Host: api.example
Authorization: Bearer bz_test_ab12cd34_…
A request without one, or with a key that is wrong, revoked or expired, gets 401 with the code auth.key_invalid and WWW-Authenticate: Bearer realm="boozie".
Kinds of credential#
| Credential | Looks like | Made by | Covers |
|---|---|---|---|
| Venue key | bz_test_… / bz_live_… | The venue's owner, in the back office under Developers | One venue |
| Host-bound key | the same | The owner, binding a venue key to one host (a sales manager) | One venue, plus /hosts/me… for that host |
| Organisation key | the same | An organisation admin, under Developers → Organisation | Some or all of an organisation's venues. See Organisations |
| OAuth access token | bz_at_test_… / bz_at_live_… | Your app, when a venue installs it | The venues the installer picked. See OAuth apps |
| Sandbox key | bz_test_… | You, from the portal | Your own sandbox venue, every scope, 30 days |
A key's secret is shown once, when it is made. Boozie keeps only a hash, so a lost key can't be recovered: make a new one and revoke the old one.
The back office's Developers page appears once Boozie has turned on Developer access for the venue. Ask us if you don't see it. A request for a venue whose Developer access is off gets 403 auth.developer_access_off.
Choosing the venue#
Every venue endpoint has the venue in its path: /venues/{venueId}/…. A venue key works only for its own venue; any other venueId gets 404 not_found, as if the venue didn't exist. Organisation keys and OAuth tokens can cover several venues, and GET /venues lists them.
Scopes#
A key holds a list of scopes. An endpoint that needs a scope the key doesn't have answers 403 auth.scope_missing, and the problem's detail names the scope.
| Scope | Lets the key |
|---|---|
venue:read | Read the venue: details, tables, hours, menu and sessions |
bookings:read | Read bookings |
bookings:write | Make and change bookings (time, table, guests, remark) |
bookings:status | Confirm, reject and cancel bookings; mark arrivals |
guestlist:read | Read the guest list |
guestlist:write | Add guest-list names and mark them arrived or no-show |
customers:pii | See customers' names, phone numbers and emails (without it they are left out) |
reviews:read | Read reviews |
reviews:write | Reply to reviews |
analytics:read | Read the analytics summaries |
hosts:read | Read the key's host's own customer book, link and numbers (a host-bound key only) |
webhooks:manage | Manage webhook endpoints and see their deliveries |
Give each integration only the scopes it needs. A door-check app needs guestlist:read guestlist:write bookings:read bookings:status, not analytics:read.
Scopes and the venue's plan#
Some scopes need a feature of the venue's Boozie plan:
- Booking:
bookings:*andguestlist:*. - Analytics:
analytics:read.
What a key can do is its scopes ∩ the venue's plan. A key can hold a scope the plan lacks: its requests then get 403 auth.plan_feature until the venue moves to a plan with that feature. Nothing changes on the key itself, so an upgrade takes effect at once.
Test and live#
Test keys (bz_test_…) | Live keys (bz_live_…) | |
|---|---|---|
| Work on | the sandbox and other test environments | production |
| Base URL | https://api-dev-799b.up.railway.app/public/v1 | announced when production opens |
| Data | test data; the sandbox resets every night | real venues and real guests |
A key used on the wrong environment gets 401 auth.key_invalid, with a detail saying test keys work on the sandbox and live keys on production. The prefix tells you what a key is before you send it, so check it in your configuration.
Rate limits#
Each key may make 60 requests a minute, with bursts of up to 120 (twice its limit). Boozie can raise the limit for a key that needs more. An OAuth app's installation gets 120 requests a minute by default, shared by all its venues. Every answer says where you stand:
RateLimit-Policy: 120;w=60;burst=120;rate=60
RateLimit-Limit: 60
RateLimit-Remaining: 117
RateLimit-Reset: 42
Over the limit the answer is 429 rate_limited with Retry-After in seconds. Wait that long, then retry. See conventions.
Rolling a key#
Roll a key every few months, and at once if it may have leaked. In the back office, Roll makes a new secret for the same key, same name and scopes:
- Press Roll and copy the new secret.
- The old secret keeps working for 24 hours.
- Deploy the new secret within that day. After 24 hours the old secret stops.
If a key has leaked, Revoke it instead: it stops at once.
Keeping keys safe#
- Keep keys on your server, in a secrets store or environment variables. Never put a key in a mobile app, a browser or a public repository.
- Use a separate key for each integration and each environment, so you can revoke one without stopping the others.
- Boozie logs each key's last use. A key you don't recognise or don't use any more should be revoked.
Next: OAuth apps