How API keys work, scopes, environments, and keeping keys safe.
The Booking Pro API authenticates every request with an API key sent as a bearer token:
Authorization: Bearer bp_sk_live_...
A key is bound to exactly one company. Whatever company minted the key is the company the request acts on, you never pass a company id, and you cannot reach another company's data with your key. If a request body or query includes an id that belongs to a different company, the API rejects it.
Each key carries a set of scopes. A request that needs a scope the key does not have
returns 403 insufficient_scope. Grant only what an integration needs.
| Scope | Grants |
|---|---|
read:availability |
Read open slots |
read:catalog |
Read services and locations |
read:contacts |
Read contacts |
write:contacts |
Create and update contacts |
read:bookings |
Read bookings |
write:bookings |
Create, cancel, reschedule bookings |
read:giftcards |
Read gift cards |
read:packages |
Read package templates |
read:memberships |
Read membership plans and what a customer holds |
write:memberships |
Sell a membership to a contact |
checkin:members |
Resolve and check in members (kiosk, turnstile, biometric device) |
A key is scoped to specific locations, or to all locations in the company (an
explicit choice at mint time). Reads and writes are always confined to the key's
locations. /ping shows which locations a key can act on.
Keys are prefixed by environment:
bp_sk_live_...acts on your real data.
A sandbox test environment (bp_sk_test_...) is on the roadmap; today only live keys
are issued.
- Never put a key in browser or mobile client code. Treat it like a password.
- Store keys in a secret manager or environment variables.
- Rotate periodically: create a new key, switch traffic, then revoke the old one.
- If a key leaks, revoke it immediately in Settings -> Developers. Revocation is instant.
| Status | Meaning |
|---|---|
401 invalid_api_key |
Missing, malformed, or revoked key |
403 insufficient_scope |
Key lacks the required scope |
403 (location) |
Target is outside the key's locations |
See Errors for the full envelope.