Developer docs menu
Building
API keys
Act for one business with its own key: book directly and read its records.
Reading a business and asking for a booking need no key. A key is for the business’s own software: it books directly, and reads and writes the business’s own records.
Making a key
The business’s owner makes keys in the dashboard under Settings, AI agents & API, on a plan that includes API access. A key starts bm_live_ and is shown once, when it is made. Only a hash of it is stored, so a lost key is replaced, not recovered.
Sending it
curl https://api.bookingmachine.io/v1/account \
-H 'Authorization: Bearer bm_live_…'Or as X-Api-Key for tools that cannot set Authorization. Never put a key in a URL. GET /account needs no scope, so it is the call to check a key with.
Scopes
| Scope | What it allows |
|---|---|
| write:bookings | Hold times and make bookings directly, with no confirmation link to the customer. Also change a booking’s status and move it to a new time, with everything that follows in the dashboard: the customer’s emails, and any refund, balance charge or no-show fee the business has set up. |
| read:bookings | Read the business’s bookings, with the customer on each. |
| read:customers | Read the business’s customer list. |
| write:customers | Add a customer. |
| read:quotes | Read the quotes the business has written or been asked for. |
| write:quotes | Write a quote for a customer and email it to them. |
| manage:webhooks | Add, list and remove the business’s webhook endpoints. The events carry customer details. |
Give a key only the scopes its job needs. A missing scope is refused with 403 scope_missing.
The business’s own records
Operations under /account act on the business the key belongs to, so no path names it: bookings, customers, quotes and webhook endpoints. They are listed in the API reference under Account.
Rate limits with a key
A key has its own allowance, counted per key: 300 reads and 60 writes a minute. It is separate from the allowance of callers without a key, so neither can use up the other’s. See Errors and limits.
Still have questions? Contact support