OpenBooking / Docs / Hosted
Guide

Hosted OpenBooking

Last updated 2026-11-06 · Edit on GitHub

Many businesses on one deployment (@openbooking-sh/hosted): sign-up and Studio settings, Google Calendar sync, confirmation emails, one OpenBooking app across every business, and a public booking page per business.

pnpm dev:hosted     # seeds "Studio Nord"; Studio login demo@openbooking.sh / openbooking-demo

Routes #

Path What
GET /signup, POST /api/signup, POST /api/login Owner accounts (email + password, scrypt; 7-day signed session token, revoked by logout or a password reset)
GET /studio, /studio/api/* Studio for the logged-in business, including Settings
ALL /mcp The OpenBooking app: find_business plus the seven booking tools, each taking business_id
/b/{id} The business: booking page for browsers, JSON index otherwise
/b/{id}/mcp, /b/{id}/ucp/*, /b/{id}/.well-known/* Per-business MCP, UCP and A2A card (same as a self-hosted single business)
/b/{id}/book/* Booking page API, manage links (/book/manage/{booking}?code=), confirm links (/book/confirm/{booking}), llms.txt
/b/{id}/usp/*, /b/{id}/.well-known/usp USP, when the owner turned it on (see below)
GET /b/{id}/embed.js The website snippet (see below)
GET /reset, POST /api/password/*, GET /api/verify-email Password reset and email confirmation
GET /oauth/google/callback Google Calendar connection

{id} is the business's URL name (studio-nord), fixed at sign-up, and is also its business_id and the venue id on its bookings.

Self-serve setup #

Sign-up asks for the business name, type, city, owner name, email and password, and creates a business that is bookable straight away: the owner as the only staff member, typical services for the type (example NOK prices), weekday hours, and free cancellation until 24 hours before.

The owner then lands on /setup, one short screen per step, each saved as they go:

  1. Import from your website (optional): POST /studio/api/import reads their site and proposes address, phone, opening hours and services. Sources: schema.org JSON-LD, page meta and tel: links, and, when ANTHROPIC_API_KEY is set, Claude reading the home page plus up to two likely prices pages. Only public http(s) addresses are fetched (every redirect re-checked), with an 8-second timeout and a 1.5 MB cap; 10 imports per business per hour.
  2. Contact: street, postal code, city, phone, one line about the business.
  3. Services: name, minutes, price; add and remove rows.
  4. Opening hours: one-tap presets, then any day adjusted.
  5. Team: names ("just me" is fine).
  6. Live: "Try it yourself" in ChatGPT and Claude, the booking page link, the Google step and the website snippet.

Everything stays editable in Studio Settings, which also has the checklist and links.

Settings are in owner terms (BusinessSettingsSchema in @openbooking-sh/studio): profile, opening hours per weekday, closed dates, staff, services (duration, price, who does it), one cancellation rule as percentages of the price, booking rules, email preferences, and whether the business is listed in the OpenBooking app. catalog.ts turns them into the provider configuration.

Deposits are set per business once it connects its own Stripe account: see Deposits (Stripe) below.

Getting found: Google, website, social #

Studio Settings has a Get found on Google and your website card with copy buttons:

  1. Google Business Profile: paste the booking page link under Bookings, so a Book button shows in Google Search and Maps.
  2. Website: one line, pasted once (Wix custom code, Squarespace code injection, WordPress via WPCode, Webflow footer code, Shopify theme.liquid):

    <script src="https://app.openbooking.sh/b/studio-nord/embed.js" async></script>

    It adds a floating Book button and a booking popup, turns existing links to the booking page (and elements with data-openbooking) into popup triggers, adds schema.org LocalBusiness data with the services, and registers the booking tools for browser agents (WebMCP) on the business's own site. Options on the tag: data-label, data-color, data-position="left", data-button="none", data-structured-data="off", data-agents="off". The booking page API allows any origin (CORS) for this; no cookies are involved.

  3. Instagram and Facebook: the booking page link in the bio and the Book now button.

The schema.org block is added by script, which Google reads; crawlers that don't run JavaScript see the booking page's own server-rendered data instead.

Google Calendar #

Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET (a Google Cloud OAuth web client with the Calendar API enabled, redirect URI {BASE_URL}/oauth/google/callback). Scopes: openid email, calendar.events, calendar.freebusy, calendar.calendarlist.readonly. Google requires app verification for these scopes before outside users can connect without warnings; plan for that.

Deposits (Stripe) #

Each business connects its own Stripe account in Studio → Settings → Online payments: paste a restricted key that may write Checkout Sessions and Refunds (or a secret key). Money goes straight to the owner, not through OpenBooking. The key is checked with Stripe before it is saved, and Studio only ever shows its last four characters.

The Stripe key sits in the business record as-is, like the Google tokens (not exported, not shown).

Assistants booking through USP #

USP is a draft standard from Wix and Stripe that lets any assistant or platform discover and book a business, signing in with a key it makes itself (no accounts). It is off for every business until the owner turns it on in Studio → Settings → AI assistants, where they also choose how bookings happen:

The business's profile is at /b/{id}/.well-known/usp (there is no profile at the root, because the root is not one business). USP's MCP binding (/b/{id}/usp/mcp, the usp_* tools) is off unless the deployment passes uspMcp: true; it then serves every business that has USP on, with the same consent setting. Businesses saved before the setting existed have no assistants block and count as off. For several instances or serverless, pass uspState (postgresStores(db).usp, which the Vercel entry does when DATABASE_URL is set): it holds owners, credentials and replay protection, shared by every instance and kept apart per business. When a platform calls, hosted fetches the platform's own profile (public internet only, cached, shared by all businesses) and uses only what both sides support. Protocol details are in SPEC-NOTES.md.

API keys for the business's own website #

A site with no backend (an AI-built static page, say) can call its business's booking API straight from the browser or from a function. In Studio → Settings → API keys the owner makes a key and gives it a name and one of two scopes:

Send it as x-openbooking-key: obk_… or as Authorization: Bearer obk_…. A key works for its own business only. The secret is shown once; only a hash is stored. Studio lists each key with when it was last used and revokes it on its own, and each key is limited to 300 calls a minute. A bad, revoked or other business's key gets 401 invalid_api_key, and a read key asked to book gets 403 insufficient_scope. A business holds at most ten active keys, and closing the account deletes them.

A key is not a lock. Public access still works without one, as before, so a visitor (or a scraper) can call the same endpoints with no key. What a key adds is a name for who is calling, a way to give a site read-only access, a limit per site, and a way to cut one site off. A key in a browser's JavaScript is visible to anyone who opens the page, so give a site that only shows availability a read key. UCP, A2A and USP are not governed by keys. Studio never accepts one.

Emails #

Set RESEND_API_KEY (and MAIL_FROM, default bookings@openbooking.sh, which must be a verified Resend domain). Without it nothing is sent (pnpm dev:hosted prints them instead).

Owner accounts #

Storage #

Everything stateful sits behind an interface with an in-memory default, and @openbooking-sh/postgres implements all of them. postgresStores(db) returns them ready to pass to createHostedApp:

Option Interface Postgres Notes
businesses BusinessStore PostgresBusinessStore JSON record; unique id and lower-cased owner email.
bookings BookingRecordStore PostgresBookingStore One store for all businesses (venue id = business id).
idempotency IdempotencyStore PostgresIdempotencyStore Shared; hosted prefixes keys with the business id.
activityFor (id) => ActivityLog PostgresActivityLog One scope per business.
notificationLog NotificationLog PostgresNotificationLog Insert-if-absent, so no email goes out twice.
suppressions SuppressionList PostgresSuppressionList Unsubscribed addresses as hashes, per business.
apiKeys ApiKeyStore PostgresApiKeyStore Website API keys as hashes, per business.
calendarLinks CalendarLinkStore PostgresCalendarLinkStore Booking id → Google event.
rateLimiter RateLimiter PostgresRateLimiter Fixed windows shared by every instance.
uspState UspStateStore PostgresUspState USP owners, credentials, replay memory; scoped per business.

With DATABASE_URL set, the Vercel entry (OPENBOOKING_MODE=hosted) and pnpm dev:hosted use all of them and create the tables on start.

Encrypting stored credentials #

A business record holds the owner's Google Calendar tokens and Stripe key (and its webhook secret). Set TOKEN_ENCRYPTION_KEY and they are encrypted (AES-256-GCM) before they reach the store, so a leaked backup or a copied database branch cannot use them. Each value is tied to its business and field. Make a key with node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" (32 bytes, base64 or 64 hex characters) and keep it in the environment, not in the database.

Customer data #

A customer can ask the business what it holds about them, or to delete it. The owner does it in Studio, under Settings, Customer data: enter the customer's email address or phone number, then download their data (a JSON file of their bookings) or delete it. Deleting removes the name, contact details and notes from their bookings. The bookings themselves (time, service, status) stay, so the calendar history and statistics remain right. Phone numbers match on their digits, email addresses ignore case.

The owner's own data #

Under Settings, Your account the owner can download everything stored about the business (account, settings and every booking, as JSON; never the password hash or Google tokens) and close the account. Closing asks for the password and deletes, in this order: calendar links, activity and booked-via attribution, idempotency records, all bookings, and last the account itself, so a failure half way leaves an account the owner can still log into and retry. The booking page stops working and the id is free to register again.

Studio's Agent log lists every call an assistant made. For a confirm, a move or a cancellation that went through on user_confirmed: true, the entry also keeps what the booking said at that moment: service, time, party size, price, deposit and the cancellation terms (the text an agent must show the user), plus the fee and refund when cancelling. With the agent's name, protocol and the time, that answers "what did the customer agree to, and through whom". It shows under the action in the log and in the booking's history.

Observability #

All optional, set as environment variables on the Vercel project:

Variable Tool What it does
SENTRY_DSN Sentry (EU region) Server errors plus anything logged with console.error (failed emails, calendar syncs). No IPs, cookies or request bodies.
POSTHOG_KEY, POSTHOG_HOST PostHog (EU cloud by default) Server events keyed by business id: business_signed_up, email_verified, website_imported, google_calendar_connected, password_reset, slot_held, booking_confirmed and booking_cancelled with their channel. Plus a cookieless browser snippet on owner pages (sign-up, setup, Studio), never on customer booking pages or the password reset page. It counts page views only: no autocapture, heatmaps or session recording, and all text is masked.
SLACK_WEBHOOK_URL Slack incoming webhook Operator notifications: new business, email confirmed, Google connected, every booking and cancellation with its channel, server errors (at most one a minute). Business names only. Previews prefix [preview].

No customer names, emails or phone numbers are sent to any of them. Background work (emails, calendar sync, analytics, Slack) finishes after the response through waitUntil(hosted.idle()).

Cold starts #

Each new function instance logs one line, with stage names and milliseconds only:

[openbooking] cold start: imports=1900ms db_connect=850ms migrate=12ms app=6ms boot=870ms

Measured locally (PGlite, so no network): app is 2 to 5 ms, the up-to-date migrate is one query, and module loading dominates (Sentry alone is about 1 to 3 seconds on a loaded laptop). A real cold start adds what only production shows: Neon waking a suspended compute (typically a few hundred milliseconds up to a couple of seconds) and the round trips between the function and the database.

Settings that matter, none of them code:

Abuse and capacity #

An audit of what a stranger on the internet can do, and what happens when the free plans run out (OPE-89). What the code does is checked against the code; the plan limits are not, so read the numbers in your own Neon and Vercel dashboards.

Limited in code

Not limited in code (known gaps)

Plan limits (cannot be fixed in code)

Not done yet #

This page is generated from docs/HOSTED.md in the open-source repository. To fix something, change it there.