Keys and security

Every request carries a key, as a bearer token:

Authorization: Bearer pk_live_…

Keys are made in Settings → Developers, by an admin of the workspace. Book-ah shows a key once, when it is made, and after that only its first characters. Book-ah keeps only a fingerprint of it, so if a key is lost, make a new one.

Two kinds of key

	Publishable pk_live_…	Secret sk_live_…
Where	In your website’s pages	On your website’s server
Works from	Only the website addresses you list on the key	Anywhere that is not a browser
Can	Read rooms, prices and availability; send booking requests	All of that, and read booking requests back

A publishable key is meant to be seen. Anyone can read it from your page. That is why it works only from the addresses you list, and why it cannot read what guests sent.

A secret key must never be in a page. Book-ah refuses it from a browser (any request with an Origin header), so a secret key pasted into a page fails at once rather than leaking.

Website addresses

List each address your pages are served from, such as https://www.example.com. To allow every subdomain one level down, list https://*.example.com (it allows www.example.com and book.example.com, not example.com itself or a.b.example.com). For testing, http://localhost:3000 works too.

A request from an address that is not listed is refused with 2003.

Rotating a key

Rotate makes a new key with the same name, kind and addresses. The old one keeps working for 24 hours, so you can switch your website over without an outage. Revoke stops a key at once.

Limits

• 600 calls a minute for each key.
• With a publishable key, 120 calls a minute for each visitor, and the booking request limit of the Book-ah site for each visitor.
• A few booking requests an hour for each guest email address.

Over a limit, the answer is 429 with errorCode 5001 and a Retry-After header: wait that many seconds and try again.