Authentication
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_...Keys are per-company
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.
Scopes
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, what a customer holds, and a membership's check-ins |
checkin:members | Resolve and check in members (kiosk, turnstile, biometric device) |
read:classes | Read the class timetable and rosters |
write:classes | Book, cancel, and check contacts in to classes |
read:webhooks | List webhook endpoints and their delivery log |
write:webhooks | Register and delete webhook endpoints, rotate their signing secret |
Locations
A key is scoped to specific locations, or to all locations in the company (an
explicit choice at mint time). Everything that belongs to a location (availability,
services, bookings, gift cards, packages, membership plans, a contact's memberships and
their check-ins, classes, and webhook endpoints) is confined to the key's locations: a
location-limited key never sees or changes another location's records, and a record of
another location answers 404, exactly like one that does not exist. Records that
belong to no single location (company-wide) are visible only to an all-locations key.
Contacts are shared by every location of the business, so read:contacts and
write:contacts reach every contact. /ping shows which locations a key can act on.
Environments
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.
Keeping keys safe
- 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.
Errors
| 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.