Authentication
API keys for /api/v1, manage tokens for guests, and the endpoints that need no credential.
Which credential a request needs is decided by the endpoint, not by the caller.
| Endpoints | Credential |
|---|---|
/api/v1/* | An API key: Authorization: Bearer sk_live_… |
/api/book/{slug}/* | None. These are the calls a business's own booking page makes. |
/api/book/{slug}/manage/{token} | The manage token from the guest's booking link. |
/api/mcp | None. Nothing it reads is private. |
API keys
An organization admin creates keys in the dashboard under Developer; API access is included on Pro (Venue Pro for venues). The raw key is shown once, when it is created. Send it as Authorization: Bearer sk_live_… and nowhere else: no query parameter, custom header or cookie, because a credential in a URL ends up in logs and browser history.
- Scopes are the whole permission model. A key carries
resource:actionscopes, never a role, andwritedoes not implyread. - Engine endpoints check the engine. A key from a table-reservations organization gets
403 wrong_verticalfrom an appointments endpoint, and the other way round, even when it holds the scope. - Keys cannot manage keys. Keys are created and revoked only in the dashboard, so a leaked key cannot mint another.
- Errors carry a stable
codebeside theerrorsentence:missing_authorization,invalid_key,key_revoked,key_expired,organization_inactive(401);insufficient_scope,wrong_vertical,plan_required(403);rate_limited(429). Match oncode, never on the sentence. - Rate limits are per key: a fixed 60-second window, 120 requests a minute by default. Every response states the policy in
RateLimit-Policy, a response to a known key adds what is left inRateLimit, and a 429 addsRetry-After. - Every list is
{ data, nextCursor }, keyset paged and camelCase.nextCursoris null exactly when there are no more rows. /api/v1/is a real version. A breaking change ships as/api/v2/, andv1keeps answering unchanged for at least 6 months withDeprecation(RFC 9745) andSunset(RFC 8594) headers on every response. Only a security fix can shorten that window, and the notice says why.
Guest manage tokens
Every booking has a manage token. It reaches the guest only through their confirmation email and the link in it, and whoever holds it can move or cancel that one booking, answer its intake form or message the venue, within the venue's own rules: its notice period, and whether it lets guests make changes at all. The /api/v1 booking lists never return it, so a program that reads bookings cannot act as the guest.
Endpoints with no credential
The booking endpoints under /api/book/{slug} and the MCP endpoint take no credential, because they serve what a business's public booking page already shows any visitor. The ones that write are rate limited per visitor.