Skip to content

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.

EndpointsCredential
/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/mcpNone. 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:action scopes, never a role, and write does not imply read.
  • Engine endpoints check the engine. A key from a table-reservations organization gets 403 wrong_vertical from 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 code beside the error sentence: missing_authorization, invalid_key, key_revoked, key_expired, organization_inactive (401); insufficient_scope, wrong_vertical, plan_required (403); rate_limited (429). Match on code, 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 in RateLimit, and a 429 adds Retry-After.
  • Every list is { data, nextCursor }, keyset paged and camelCase. nextCursor is null exactly when there are no more rows.
  • /api/v1/ is a real version. A breaking change ships as /api/v2/, and v1 keeps answering unchanged for at least 6 months with Deprecation (RFC 9745) and Sunset (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.

On this page