# Authenticating with Bookatu

Bookatu is a booking platform for salons, spas, trainers, photographers, clinics
and similar businesses. This document tells a software agent how to get a credential
and what that credential can reach.

Two rules shape everything below.

1. Every credential is bound to exactly one business. A credential issued for one
   business can never read or change another business's data.
2. A human at that business issues or approves every credential. There is no way for
   an agent to sign itself up or to grant itself access to a business.

## Surfaces, and what each one accepts

| Surface | URL | Accepts |
| --- | --- | --- |
| MCP server (JSON-RPC 2.0 over HTTP POST) | https://bookatu.com/api/mcp | OAuth access token, or API key |
| REST API v1 | https://bookatu.com/api/v1/{slug} | API key |
| Booking MCP server, for a person's own assistant | https://bookatu.com/api/mcp/book | none (the person confirms by email) |

The public REST endpoints (business profile, services, staff, availability, booking)
take no credential at all. If your agent only needs to find a business and book an
appointment for someone, use those and stop reading here. The machine-readable
description is at https://bookatu.com/api/openapi.json.

## Discovery

Read the metadata first and follow it, rather than hardcoding the URLs in this file.

- Authorization server metadata (RFC 8414): https://bookatu.com/.well-known/oauth-authorization-server
- Protected resource metadata (RFC 9728): https://bookatu.com/.well-known/oauth-protected-resource/api/mcp
- OpenAPI 3.1 for the REST API: https://bookatu.com/api/openapi.json
- Capabilities (endpoints, MCP tool families, auth modes): https://bookatu.com/api/capabilities

An unauthenticated POST to the MCP endpoint answers 401 and names its own metadata
document, which is the pointer to start OAuth from:

```
WWW-Authenticate: Bearer realm="Bookatu MCP", resource_metadata="https://bookatu.com/.well-known/oauth-protected-resource/api/mcp"
```

## Option 1: OAuth 2.1 authorization code with PKCE

This is the path for MCP clients. Clients are public: no client secret is issued, and
asking for one changes nothing. PKCE with S256 is the proof of possession and it is
required, not optional.

### 1. Register the client (RFC 7591)

```bash
curl -X POST https://bookatu.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My scheduling agent",
    "redirect_uris": ["https://agent.example.com/callback"]
  }'
```

Register between 1 and 10 redirect URIs. Each must be https, or http on localhost or
127.0.0.1 for a native loopback, and none may have a fragment (a `#`). The response
carries a `client_id` and no `client_secret`. A mistake is refused with 400 and an
`error_description` that names the field.

Registration is open, and on its own it grants nothing. A registered client can reach
no business until a human approves it.

### 2. Send the business owner to the consent page

Open https://bookatu.com/oauth/authorize in a browser with:

| Parameter | Value |
| --- | --- |
| `response_type` | `code` (the only value supported) |
| `client_id` | from registration |
| `redirect_uri` | exactly one of the URIs you registered |
| `code_challenge` | BASE64URL(SHA256(code_verifier)) |
| `code_challenge_method` | `S256` (`plain` is rejected) |
| `state` | recommended; echoed back on the redirect |
| `scope` | optional; the supported values are `read` and `write` |
| `resource` | optional (RFC 8707); when sent it must be `https://bookatu.com/api/mcp` |

The person signs in to Bookatu, picks which one of their businesses this
connection is for, and picks whether it is read-only or read-write. What your client
asked for in `scope` only sets the default on that page. The approver decides, and
Bookatu re-checks on the server that they are an owner or admin of the business
they picked, with a confirmed email. Until their email is confirmed, the page asks
them to confirm it first.

If they decline, you are redirected back with `error=access_denied`. A suspended
business cannot be connected: the page leaves it out, and approving for it is refused.

An unknown `client_id` or a `redirect_uri` the client never registered is rendered as
an error on the page and never redirected anywhere, so the authorize endpoint cannot
be turned into an open redirect. Every other mistake in the request is shown on the
page the same way: a `response_type` other than `code`, a missing or short
`code_challenge` (it must be 43 to 128 characters, and S256 makes 43), a
`code_challenge_method` other than `S256`, a `resource` that is not `https://bookatu.com/api/mcp`, or
a parameter sent more than once. Your client gets no
`error=invalid_request` or `error=invalid_target` callback for these, so check the
request before you open the page. The only two ways back to your
`redirect_uri` are the code after the person approves and
`error=access_denied` when they decline.

### 3. Exchange the code for tokens

```bash
curl -X POST https://bookatu.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=YOUR_CODE \
  -d client_id=YOUR_CLIENT_ID \
  -d code_verifier=YOUR_VERIFIER \
  -d redirect_uri=https://agent.example.com/callback
```

Form encoding is the spec form; a JSON body is tolerated. The response carries
`access_token`, `token_type`, `expires_in`, `refresh_token` and `scope`. Read the
lifetime from `expires_in` rather than hardcoding one.

An authorization code is single use. Presenting the same code twice revokes every
token that code minted, so do not retry a failed exchange with the same code.

If you send `resource` here (RFC 8707), send the one you sent to authorize. Any other
address is refused with 400 and `error=invalid_target` before the code is used, so
you can still redeem it with the right one.

The token and revocation endpoints are rate limited per address and per client, far
above what a connector needs. Over the limit you get 429 with
`error=too_many_requests` and a `Retry-After` header: wait that many seconds.

### 4. Call the MCP server

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

### 5. Refresh

```bash
curl -X POST https://bookatu.com/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token=YOUR_REFRESH_TOKEN \
  -d client_id=YOUR_CLIENT_ID
```

Refresh tokens rotate. Every refresh returns a new pair and retires the old one, so
store the newest pair and discard the previous. Replaying a retired refresh token
revokes the whole connection, which is the OAuth 2.1 reuse-detection rule.

Send `client_id` on every refresh, as OAuth 2.1 asks of a public client. A refresh
without it can be refused with 400 and `error=invalid_request`. That refusal does
not use up the refresh token, so send it again with `client_id`.

### 6. Revoke (RFC 7009)

```bash
curl -X POST https://bookatu.com/api/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d token=YOUR_TOKEN
```

Revoking either half of a pair disconnects the whole connection. The endpoint answers
200 for tokens it does not recognise as well, so it cannot be used to find out whether
a token exists.

The business owner can also disconnect your app at any time from their dashboard under
Settings, then Developer API, and they do not have to tell you. Treat a sudden 401 as a
signal to start the flow again.

## Option 2: a static API key

For agents with no browser in the loop. An owner or admin of the business, with a
confirmed email, creates a key in the dashboard under Settings, then Developer API,
and pastes it into your agent. That page
is https://bookatu.com/{slug}/admin/api, where `{slug}` is that business's own slug and the page needs them
signed in, so it is not a URL you can open. There is no API that mints keys.

Send it either way:

```
Authorization: Bearer bk_live_YOUR_KEY
X-Api-Key: bk_live_YOUR_KEY
```

A key starts with `bk_live_`. It is shown once at creation and only its hash is
stored, so it cannot be retrieved later. A key can carry an expiry, is checked against
revocation on every request, and records when it was last used. Its access level,
read-only or read-write, is chosen when it is created.

Never put a key in browser or mobile client code. Call key-protected endpoints from
your own server.

API keys work on both the MCP server and the v1 REST API. OAuth access tokens work on
the MCP server only.

## What a credential can do

- One business. Every read and every write is scoped to the business the credential
  belongs to. There is no cross-business call, whatever you pass in the arguments.
- Read-only or read-write. A read-only credential runs the read tools its scopes
  reach. A write tool returns HTTP 403 carrying a JSON-RPC error that names the tool.
- Clients' names, emails and phone numbers. An app connected through OAuth reads
  them (list_customers, form responses, and the client on a booking request or a
  class roster) only when the owner ticked the box for them on the consent page.
  Without it the requests and rosters come without the client's details, and
  list_customers answers 403 naming customers:read.
- No deletes. The MCP server exposes no delete tool of any kind, on purpose. Removing
  data stays a human action in the dashboard. A sandbox (a test business a developer
  makes) also lists sandbox_outbox, sandbox_payments, sandbox_simulate and
  sandbox_reset, never a live business; sandbox_reset wipes the sandbox's made-up data and seeds it again, with
  its own test key only (https://bookatu.com/en-nz/developers/testing-ai-agents).
- Sending an email campaign is not exposed either. An agent can draft one; the owner
  sends it.
- Clients' answers to intake and consent forms never leave the admin dashboard,
  whatever credential you hold.
- Requests are rate limited per credential, and monthly usage is metered and visible
  to the business owner.
- On some plans the AI and API add-on has to be active before key-protected endpoints
  and the MCP server will answer. The consent page marks a business that is not
  entitled, and says so before the owner approves.

## Not supported

These will fail, so do not build against them.

- Client secrets and confidential clients. `token_endpoint_auth_methods_supported` is
  `["none"]`.
- Any grant other than `authorization_code` and `refresh_token`. Anything else gets
  `unsupported_grant_type`, including the client credentials grant.
- `code_challenge_method=plain`. S256 only.
- Self-service signup by an agent. No endpoint creates a business or a user account.
- OAuth access tokens against the v1 REST API. Use an API key there.

## More

- Developer documentation: https://bookatu.com/en-nz/developers
- Contact: hello@bookatu.com
