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.

Note: A key works for the business that made it and no other. A request with a key that is wrong, revoked or expired is refused. It is never served as if it had no key.

Scopes

ScopeWhat it allows
write:bookingsHold 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:bookingsRead the business’s bookings, with the customer on each.
read:customersRead the business’s customer list.
write:customersAdd a customer.
read:quotesRead the quotes the business has written or been asked for.
write:quotesWrite a quote for a customer and email it to them.
manage:webhooksAdd, 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.