Build on Bookatu.
REST, webhooks & MCP

Authentication

The public endpoints (business, services, staff, availability, book) require no authentication and can be called from any origin. The key-protected endpoints (customers, appointments) and the MCP server need an API key issued from your admin dashboard at /{slug}/admin/api.

The customer booking-management endpoints take no API key: the appointment id IS the capability. Ids are apt_ followed by a 16-character nanoid — about 96 bits from a 64-character alphabet, the same order of unguessability as a magic link — and are only ever handed to the person who booked (their confirmation email and booking-success screen). They are also scoped to the business in the URL, so a valid id from one business can never be read or acted on through another's. Treat a booking id like a password: it lets the holder view, move or cancel that one booking, and nothing else. Every one of these endpoints is rate limited per IP, returns only what the person who booked already knows, and answers a 404 for anything that is not this business's booking.

Pass the key as a Bearer token in the Authorization header, or in the X-Api-Key header.

Authorization: Bearer bk_live_YOUR_KEY
X-Api-Key: bk_live_YOUR_KEY

• Keys are issued from the admin dashboard and shown exactly once at creation. Store them in a secret manager or environment variable; they cannot be retrieved again.
• A key is a random token (bk_live_ followed by a 32-character id). Only its SHA-256 hash is stored, and verification uses a timing-safe comparison.
• Keys support an optional expiry, are checked against revocation on every request, and record a lastUsedAt timestamp so you can audit usage.
• Each key has a scope: read-write (full access) or read-only. A read-only key may call the GET endpoints and read-only MCP tools, but write endpoints — creating or cancelling a booking — return 403. Issue read-only keys for integrations that only need to read your data.
• Revoke a key immediately from the dashboard if it is ever exposed. Revoked and expired keys stop authenticating at once.

Base URL & CORS

https://bookatu.com/api/v1/{slug}

Replace {slug} with the business URL slug visible in your admin and public booking link. All responses are application/json. Errors always return { ok: false, error: "..." } (validation errors also include a fieldErrors map). Stack traces are never leaked.

The public endpoints (business, services, staff, availability, book) return Access-Control-Allow-Origin: * and answer the CORS preflight (OPTIONS) with 204, so any site or agent can call them directly from a browser. Key-protected endpoints deliberately do NOT send the wildcard — their allowed CORS origin is the platform's own origin, because business data has no legitimate cross-origin browser use. The customer booking-management endpoints (everything under /booking/{id}) do not send it either, and answer no preflight: they are authorised by the booking id itself, which has no business being replayed from a third-party page. Neither restriction affects server-to-server or native mobile callers, which are not subject to browser CORS at all. Never embed a bk_live_ key in browser or mobile-client code — call key-protected endpoints from your own server.

GET /business

GET /api/v1/{slug}/business

Business profile + opening hours

The business profile: name, industry, country, currency, timezone, locale, address, phone, the public booking link, and the full week of opening hours. Lets an agent introduce the business and know when it is open before checking availability. No authentication required.

curl https://bookatu.com/api/v1/your-salon/business

{
  "name": "Parnell Nails",
  "slug": "parnell-nails",
  "industry": "nails",
  "country": "NZ",
  "currency": "NZD",
  "timezone": "Pacific/Auckland",
  "locale": "en-NZ",
  "address": "12 Queen St, Auckland",
  "phone": "09 555 0100",
  "bookingUrl": "https://bookatu.com/parnell-nails/book",
  "hours": [
    { "weekday": 0, "open": false, "openMin": null, "closeMin": null, "breakStartMin": null, "breakEndMin": null },
    { "weekday": 1, "open": true,  "openMin": 540,  "closeMin": 1080, "breakStartMin": 780, "breakEndMin": 840 },
    { "weekday": 2, "open": true,  "openMin": 540,  "closeMin": 1080, "breakStartMin": null, "breakEndMin": null },
    { "weekday": 3, "open": true,  "openMin": 540,  "closeMin": 1080, "breakStartMin": null, "breakEndMin": null },
    { "weekday": 4, "open": true,  "openMin": 540,  "closeMin": 1080, "breakStartMin": null, "breakEndMin": null },
    { "weekday": 5, "open": true,  "openMin": 540,  "closeMin": 1140, "breakStartMin": null, "breakEndMin": null },
    { "weekday": 6, "open": true,  "openMin": 600,  "closeMin": 960,  "breakStartMin": null, "breakEndMin": null }
  ]
}

// hours always has all 7 days. weekday 0 = Sunday .. 6 = Saturday.
// openMin / closeMin are minutes from local midnight, and are null when closed.
// breakStartMin / breakEndMin are a mid-day closure (Monday above shuts 1pm to
// 2pm) and are null when the day runs straight through. A day with a break
// trades openMin-breakStartMin and breakEndMin-closeMin, and NOTHING between:
// treat the outer pair alone as open all day and you will send someone to a
// locked door.

GET /services

GET /api/v1/{slug}/services

List active, online-bookable services

The org's public profile plus every service that is active and bookable online, ordered by sort order then name. Use a service id and durationMin when checking availability and booking. No authentication required.

curl https://bookatu.com/api/v1/your-salon/services

{
  "org": {
    "name": "Parnell Nails",
    "slug": "parnell-nails",
    "currency": "NZD",
    "timezone": "Pacific/Auckland"
  },
  "services": [
    {
      "id": "svc_abc123",
      "name": "Gel Manicure",
      "description": "Long-lasting gel polish with cuticle care.",
      "category": "Nails",
      "durationMin": 60,
      "priceCents": 7500,
      "currency": "NZD"
    }
  ]
}

// description is the service description, or null when none is set.

GET /staff

GET /api/v1/{slug}/staff

List bookable team members

The bookable team members (id, name, title, bio) so an agent can offer "book with X". Public-facing fields only — never staff email or phone. No authentication required.

curl https://bookatu.com/api/v1/your-salon/staff

{
  "org": { "name": "Parnell Nails", "slug": "parnell-nails", "timezone": "Pacific/Auckland" },
  "staff": [
    { "id": "stf_abc", "name": "Anna", "title": "Senior Nail Tech", "bio": null }
  ]
}

// title and bio are null when not set.

GET /availability

GET /api/v1/{slug}/availability

Open slots for a service

Bookable slots for a service across a date window. The engine accounts for opening hours, existing appointments, buffer times, resources and minimum booking notice. Each slot's startAt is a UTC ISO 8601 string ready to pass straight to a booking call. No authentication required. This is the read for a NEW booking: to move an existing one, use GET /booking/{id}/availability instead, because this read counts that booking's own slot as busy.

curl "https://bookatu.com/api/v1/your-salon/availability?serviceId=svc_abc123&from=2026-06-10&to=2026-06-14"

{
  "org": { "name": "Parnell Nails", "slug": "parnell-nails", "timezone": "Pacific/Auckland" },
  "days": [
    {
      "date": "2026-06-10",
      "open": true,
      "slots": [
        { "startMin": 540, "startAt": "2026-06-09T21:00:00.000Z" }
      ]
    },
    { "date": "2026-06-11", "open": false, "slots": [] }
  ]
}

// startMin is minutes from local midnight; startAt is the UTC instant to book.

POST /book

POST /api/v1/{slug}/book

Create a booking (online source)

The customer-facing booking call. The slot is validated server-side (race-condition safe), a customer record is matched by email then phone or created, and a booking reference is returned. As an online-source booking it fully respects availability and minimum notice. When a deposit is required the booking is pending and the response includes a payLink to surface to the customer. No authentication required.

curl -X POST https://bookatu.com/api/v1/your-salon/book \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "svc_abc123",
    "startAt": "2026-06-10T09:00:00Z",
    "name": "Alex Smith",
    "email": "alex@example.com",
    "phone": "+64 21 555 0100"
  }'

{
  "ok": true,
  "ref": "VRD-7QK2M9",
  "appointmentId": "apt_abc123",
  "status": "confirmed",
  "needsPayment": false
}

// When a deposit is required, status is "pending" and a payLink is returned:
{
  "ok": true,
  "ref": "VRD-7QK2M9",
  "appointmentId": "apt_abc123",
  "status": "pending",
  "needsPayment": true,
  "payLink": "https://bookatu.com/your-salon/book/success?apt=apt_abc123"
}

GET /booking/{id}

No API key. Authorised by the appointment id in the path.

GET /api/v1/{slug}/booking/{id}

Read one booking (the customer's own)

The JSON twin of the manage-booking page a customer reaches from their confirmation email: their booking, its service, its team member, its price and deposit, plus the business's cancellation policy. Authorised by the appointment id alone — no API key, no account — and deliberately narrow: only what the person who booked already knows. No customer record, no notes, no other bookings. Rate limited to 30 requests per IP every 5 minutes.

curl https://bookatu.com/api/v1/your-salon/booking/apt_abc123

{
  "org": {
    "slug": "parnell-nails",
    "name": "Parnell Nails",
    "currency": "NZD",
    "timezone": "Pacific/Auckland"
  },
  "booking": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "status": "confirmed",
    "startAt": "2026-06-10T21:00:00.000Z",
    "endAt": "2026-06-10T22:00:00.000Z",
    "durationMin": 60,
    "service": "Gel Manicure",
    "staff": "Anna",
    "priceCents": 7500,
    "depositCents": 2000,
    "addOns": [{ "name": "Nail art", "priceCents": 1500 }]
  },
  "policy": {
    "cancellationWindowHours": 24,
    "forfeitDepositOnLateCancel": true
  }
}

// policy is the business's cancellation policy: cancelling or moving more than
// cancellationWindowHours before the start is free, and inside that window a
// paid deposit is kept when forfeitDepositOnLateCancel is true. ref and staff
// are null when unset; addOns is [] when there are none.

GET /booking/{id}/availability

No API key. Authorised by the appointment id in the path.

GET /api/v1/{slug}/booking/{id}/availability

Open slots for MOVING this booking

Bookable slots for moving an existing booking, across a date window. This differs from GET /availability in two ways that matter: the booking's own slot is EXCLUDED from the busy set (otherwise an appointment's own hold hides the very time its owner is trying to shift around), and the fit uses the booking's own service and its own length — which is not always the service's default, because an add-on or a duration override can make the booking longer. Pass a returned startAt straight to POST /booking/{id}/reschedule. Authorised by the appointment id alone. Rate limited to 30 requests per IP every 5 minutes.

curl "https://bookatu.com/api/v1/your-salon/booking/apt_abc123/availability?from=2026-06-10&to=2026-06-14"

{
  "org": { "slug": "parnell-nails", "name": "Parnell Nails", "timezone": "Pacific/Auckland" },
  "booking": { "id": "apt_abc123", "durationMin": 60 },
  "days": [
    {
      "date": "2026-06-10",
      "open": true,
      "slots": [
        { "startMin": 540, "startAt": "2026-06-09T21:00:00.000Z" }
      ]
    },
    { "date": "2026-06-11", "open": false, "slots": [] }
  ]
}

// booking.durationMin is the length being fitted (the booking's, not the
// service's default). startMin is minutes from local midnight; startAt is the
// UTC instant to send back when rescheduling.

POST /booking/{id}/reschedule

No API key. Authorised by the appointment id in the path.

POST /api/v1/{slug}/booking/{id}/reschedule

Move a booking to a new time

The customer-facing reschedule — the same call the manage-booking web page makes, with the same strict rules. The new time is validated as a real, open slot: opening hours, existing bookings, buffers, resources and the business's minimum booking notice all apply, and the booking's own hold is excluded so it can be moved within its own slot. A time that is not bookable returns 409 with the reason, and nothing changes. The booking keeps its team member unless the availability engine has to reassign it, and its length is unchanged. Moving a booking fires the booking.rescheduled webhook and updates any connected calendar. Only an upcoming pending or confirmed booking can be moved: a cancelled, completed, no-show or past booking returns 409 — the same rule as the web page, so a cancelled booking can never be quietly reinstated. Rate limited to 10 requests per IP every 10 minutes.

curl -X POST https://bookatu.com/api/v1/your-salon/booking/apt_abc123/reschedule \
  -H "Content-Type: application/json" \
  -d '{ "startAt": "2026-06-12T21:00:00.000Z" }'

{ "ok": true, "startAt": "2026-06-12T21:00:00.000Z" }

// startAt echoes the time that was taken, so the new booking can be rendered
// without a second read.

POST /booking/{id}/cancel

No API key. Authorised by the appointment id in the path.

POST /api/v1/{slug}/booking/{id}/cancel

Cancel a booking (the customer's own)

The customer-facing cancellation — the same call the manage-booking web page makes, so the cancellation policy, any deposit refund or forfeiture, the booking.cancelled webhook and the waitlist re-offer are identical however it is triggered. The forfeited flag says whether a paid deposit was kept under the policy, which an app needs in order to tell the person the truth on the confirmation screen. Cancelling an already-cancelled booking is idempotent (alreadyCancelled: true), so a retry after a dropped connection is safe. Rate limited to 10 requests per IP every 10 minutes.

curl -X POST https://bookatu.com/api/v1/your-salon/booking/apt_abc123/cancel

{ "ok": true, "alreadyCancelled": false, "forfeited": false }

// forfeited is true when a paid deposit was kept under the cancellation policy
// (see policy on GET /booking/{id}).

GET /customers

GET /api/v1/{slug}/customers

List customers

Up to 1000 customers in this org (id, name, email, phone), ordered by name. Requires a valid API key whose org matches the {slug}.

curl https://bookatu.com/api/v1/your-salon/customers \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "customers": [
    { "id": "cus_xyz", "name": "Alex Smith", "email": "alex@example.com", "phone": "+64211234567" }
  ]
}

// Capped at 1000 customers, ordered by name.

GET /appointments

GET /api/v1/{slug}/appointments

List appointments

By default, upcoming appointments with status pending or confirmed whose startAt is now or later, ordered by start time, capped at 200. Optional filters let you pull a specific window or statuses, and limit/offset page through results — when more rows may exist the response includes nextOffset. Requires a valid API key scoped to this org.

curl "https://bookatu.com/api/v1/your-salon/appointments?status=completed&from=2026-06-01&limit=50" \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "appointments": [
    {
      "id": "apt_abc123",
      "ref": "VRD-7QK2M9",
      "serviceName": "Gel Manicure",
      "startAt": "2026-06-10T21:00:00.000Z",
      "endAt": "2026-06-10T22:00:00.000Z",
      "durationMin": 60,
      "priceCents": 7500,
      "status": "confirmed",
      "customerId": "cus_xyz",
      "staffId": "stf_abc",
      "notes": null,
      "createdAt": "2026-06-01T03:12:00.000Z"
    }
  ]
}

// Only pending + confirmed, startAt >= now, oldest first, max 200 rows.

GET /services/{id}

GET /api/v1/{slug}/services/{id}

Get one service

A single active, online-bookable service by id — the same shape as a row of GET /services. No authentication required.

curl https://bookatu.com/api/v1/your-salon/services/svc_abc123

{
  "id": "svc_abc123",
  "name": "Gel Manicure",
  "description": "Long-lasting gel polish with cuticle care.",
  "category": "Nails",
  "durationMin": 60,
  "priceCents": 7500,
  "currency": "NZD"
}

GET /appointments/{id}

GET /api/v1/{slug}/appointments/{id}

Get one appointment

A single appointment by id, scoped to the key's org (a key for one business can never read another's). Same lean shape as a row of GET /appointments. A read-only key may call this. Requires a valid API key scoped to this org.

curl https://bookatu.com/api/v1/your-salon/appointments/apt_abc123 \
  -H "Authorization: Bearer bk_live_YOUR_KEY"

{
  "id": "apt_abc123",
  "ref": "VRD-7QK2M9",
  "serviceName": "Gel Manicure",
  "startAt": "2026-06-10T21:00:00.000Z",
  "endAt": "2026-06-10T22:00:00.000Z",
  "durationMin": 60,
  "priceCents": 7500,
  "status": "confirmed",
  "customerId": "cus_xyz",
  "staffId": "stf_abc",
  "notes": null,
  "createdAt": "2026-06-01T03:12:00.000Z"
}

POST /appointments

POST /api/v1/{slug}/appointments

Create a booking (admin source)

Create a booking with source: admin and the same body as POST /book. An admin-source booking deliberately bypasses online restrictions: minimum booking notice is not enforced, and — unlike POST /book — a slot conflict does NOT reject the request. The availability engine is used only to resolve a free staff member and resource; it does not block the booking. The one guard that still applies is the database uniqueness constraint on (staff, start time), which returns 409 if that exact staff member is already booked at that instant. Use this for trusted staff-side tools and agents acting on behalf of the business; use POST /book for customer-facing flows that must respect availability. Requires a valid API key scoped to this org.

curl -X POST https://bookatu.com/api/v1/your-salon/appointments \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceId": "svc_abc123",
    "startAt": "2026-06-10T09:00:00Z",
    "name": "Alex Smith",
    "email": "alex@example.com",
    "phone": "+64 21 555 0100"
  }'

{
  "ok": true,
  "ref": "VRD-7QK2M9",
  "appointmentId": "apt_abc123",
  "status": "confirmed",
  "needsPayment": false
}

// When a deposit is required, status is "pending" and a payLink is returned:
{
  "ok": true,
  "ref": "VRD-7QK2M9",
  "appointmentId": "apt_abc123",
  "status": "pending",
  "needsPayment": true,
  "payLink": "https://bookatu.com/your-salon/book/success?apt=apt_abc123"
}

POST /appointments/{id}/cancel

POST /api/v1/{slug}/appointments/{id}/cancel

Cancel a booking

Cancel a booking. Scoped to the key's org, so a key for one business can never touch another's data. Fires the booking.cancelled webhook and re-offers the freed slot to the waitlist. The forfeited flag is true when a paid deposit was forfeited under the cancellation policy. Cancelling an already-cancelled booking is idempotent. Requires a valid API key scoped to this org.

curl -X POST https://bookatu.com/api/v1/your-salon/appointments/apt_abc123/cancel \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer requested" }'

{ "ok": true, "id": "apt_abc123", "forfeited": false }

Webhooks

Receive a POST to your own https endpoint when bookings change, an order is paid, a form is submitted or a campaign finishes sending. Add an endpoint in your admin dashboard at /{slug}/admin/api (admins only), or let your agent register one itself with the webhooks_create MCP tool. Payloads carry no customer contact details. Fetch the full record from GET /appointments with your API key when you need more.

{
  "event": "booking.created",
  "sentAt": "2026-06-01T03:12:00.000Z",
  "data": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "service": "Gel Manicure",
    "startAt": "2026-06-10T21:00:00.000Z",
    "durationMin": 60,
    "priceCents": 7500,
    "status": "pending"
  }
}

{
  "event": "booking.cancelled",
  "sentAt": "2026-06-02T09:30:00.000Z",
  "data": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "service": "Gel Manicure",
    "startAt": "2026-06-10T21:00:00.000Z",
    "status": "cancelled"
  }
}

{
  "event": "booking.completed",
  "sentAt": "2026-06-10T23:05:00.000Z",
  "data": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "service": "Gel Manicure",
    "startAt": "2026-06-10T21:00:00.000Z",
    "status": "completed"
  }
}

{
  "event": "booking.rescheduled",
  "sentAt": "2026-06-03T11:00:00.000Z",
  "data": {
    "id": "apt_abc123",
    "ref": "VRD-7QK2M9",
    "service": "Gel Manicure",
    "startAt": "2026-06-12T21:00:00.000Z",
    "status": "confirmed"
  }
}

{
  "event": "order.paid",
  "sentAt": "2026-06-04T02:20:00.000Z",
  "data": {
    "id": "ord_abc123",
    "description": "2 items",
    "amountCents": 5400,
    "currency": "nzd",
    "items": [
      { "productId": "prd_a1", "product": "Repair Shampoo", "quantity": 1 },
      { "productId": "prd_b2", "product": "Leave-in Conditioner", "quantity": 1 }
    ]
  }
}

{
  "event": "form.submitted",
  "sentAt": "2026-06-05T20:41:00.000Z",
  "data": {
    "formId": "frm_abc123",
    "formName": "New client intake",
    "responseId": "frs_def456",
    "customerId": "cus_ghi789",
    "appointmentId": "apt_jkl012"
  }
}

{
  "event": "campaign.sent",
  "sentAt": "2026-06-06T09:00:00.000Z",
  "data": {
    "campaignId": "cmp_abc123",
    "subject": "Winter offers are live",
    "audience": "recent",
    "sent": 182,
    "recipients": 187
  }
}

Delivery & signing

Each delivery is signed with HMAC-SHA256 over the string "{timestamp}.{rawBody}", hex-encoded. Verify it before trusting the body. The endpoint secret is shown once when you create it and starts with whsec_.

• X-Bookatu-EventThe event name, e.g. booking.created.
• X-Bookatu-Signaturet={unixSeconds},v1={hmacSha256Hex}. Use t when recomputing the signature.
• X-Bookatu-AttemptDelivery attempt number, 1 to 3.
• User-AgentBookatu-Webhooks/1
• Content-Typeapplication/json

• Up to 3 attempts. Backoff between attempts is 500ms, then 1000ms, then 2000ms (the formula is capped at 4000ms). A delivery succeeds on any 2xx response; non-2xx responses, timeouts and network errors are retried.
• Each attempt times out after 4 seconds.
• Redirects are not followed (redirect: error). Endpoints must be public https URLs: localhost, .local / .internal / .localhost hosts and private, reserved, loopback and cloud-metadata IP ranges are rejected (SSRF protection), both when the endpoint is saved and again at send time.

Verify every delivery. Recompute the signature over {timestamp}.{rawBody} and compare it, in a timing-safe way, to the v1 value in X-Bookatu-Signature.

import crypto from "node:crypto";

// rawBody is the exact bytes you received (do not re-serialize).
// secret is your endpoint secret (whsec_...).
// t comes from the X-Bookatu-Signature header: "t=<seconds>,v1=<hmac>".
function verify(rawBody, t, v1, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Rate limits

There is currently no per-key rate limit enforced on the v1 REST API. That is not a promise of unlimited throughput. Build clients defensively: treat HTTP 429 and 5xx responses as retryable, back off (ideally exponentially, with jitter), and cache rarely-changing responses such as business, services and staff. Limits may be introduced in future, designed not to break well-behaved clients. The exception is the customer booking-management family under /booking/{id}, which IS limited per IP today — they carry no key, so the limit is what stops someone hammering them; each endpoint states its own budget, and a 429 always carries Retry-After.

MCP server

Bookatu exposes a Model Context Protocol (MCP) server so any AI assistant (Claude, GPT-4o, Gemini, or a custom agent) can list services, check real-time availability, create bookings, look up customer and appointment data, manage the product and service catalog, write and publish posts on the business's blog, build intake and consent forms (and require them before a service), and draft email campaigns — all in a single authenticated session. Writes require a read-write key, and there are no delete tools by design. Two deliberate limits: form-response listings are summaries only (clients' actual answers never leave the admin dashboard), and campaigns can only be drafted — there is no send or schedule tool, so mass email always stays an owner-confirmed action in the app.

https://bookatu.com/api/mcp

# Discover tools
curl -X POST https://bookatu.com/api/mcp \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# Call a tool
curl -X POST https://bookatu.com/api/mcp \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_availability",
      "arguments": {
        "serviceId": "svc_abc123",
        "from": "2026-06-10",
        "to": "2026-06-14"
      }
    }
  }'

Configure your AI assistant by pointing it at https://bookatu.com/api/mcpwith your API key. All tools are automatically scoped to the key's organisation.

Connect from Claude

Claude's custom connectors use OAuth rather than a pasted key, and the MCP server supports that flow natively. You sign in with your normal Bookatu account, pick which business to connect and whether Claude may write or only read, and Claude receives its own revocable token for that one business. Your password and your other businesses are never shared.

1. In Claude, open Settings → Connectors → Add custom connector.
2. Enter https://bookatu.com/api/mcp as the server URL and continue.
3. Claude sends you to Bookatu to sign in. You must be an owner or admin of the business you connect.
4. Choose the business and the access level (read and write, or read only), then approve.

The same rules apply as with API keys: every tool is scoped to the connected business, read-only connections are refused on any write tool, and there are no delete tools at all. Disconnect any time from Settings → Developer API → Connected apps in your dashboard, or from Claude's connector settings. The flow is the standard MCP authorization stack for any other OAuth-capable MCP client too: discovery at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource, dynamic client registration, authorization code with PKCE, and refresh token rotation.

Build an agent on Bookatu

An AI agent can run a Bookatu business end to end with two primitives: MCP tools to act (read data, create bookings, manage the catalog, draft campaigns) and signed webhooks to react (a POST arrives at the agent when something happens). Tools in, events out. That closes the loop: the agent no longer needs a human to tell it that a booking was cancelled or an order was paid.

Worked example: an agent that refills cancelled slots

# The agent registers where it wants events delivered (once, at setup)
curl -X POST https://bookatu.com/api/mcp \
  -H "Authorization: Bearer bk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "webhooks_create",
      "arguments": {
        "url": "https://agent.example.com/hooks/bookatu",
        "events": ["booking.cancelled"]
      }
    }
  }'
# → { "webhook": { "id": "whk_...", ... }, "secret": "whsec_..." }  (secret shown once)

# Later, a client cancels. Bookatu POSTs to the agent's endpoint:
POST /hooks/bookatu HTTP/1.1
X-Bookatu-Event: booking.cancelled
X-Bookatu-Signature: t=1780000000,v1=3f1c...9ab2
Content-Type: application/json

{
  "event": "booking.cancelled",
  "sentAt": "2026-07-30T02:14:00.000Z",
  "data": { "id": "apt_abc123", "ref": "VRD-7QK2M9",
            "service": "Gel Manicure",
            "startAt": "2026-08-02T21:00:00.000Z", "status": "cancelled" }
}

# The agent verifies the signature, then acts through MCP again:
# confirm the freed slot is really open...
{ "name": "get_availability",
  "arguments": { "serviceId": "svc_...", "from": "2026-08-02", "to": "2026-08-02" } }

# ...and rebook it for the next customer who asked for that time.
{ "name": "create_booking",
  "arguments": { "serviceId": "svc_...", "startAt": "2026-08-02T21:00:00.000Z",
                 "name": "Mia Chen", "email": "mia@example.com", "phone": "+64211234567" } }