# Authentication for Bella Booking

This document is for agents and developers. It describes the credentials Bella actually accepts. This origin (https://bellabooking.com) is a **discovery host**, not an authorization server. There is no `/.well-known/openid-configuration` or OAuth Protected Resource metadata here on purpose.

## 1. Website-booking API (self-serve)

The public booking integration is REST, not MCP.

| | |
| --- | --- |
| Base URL | https://api.bellabooking.com |
| Header | `x-api-key: bella_live_{keyId}_{secret}` |
| Who issues the key | The business, in **Settings → Integrations** (Professional plan) |
| Bound to | One location. A key cannot be moved. |
| Human reference | https://docs.bellabooking.com/developers/api-keys |

There is no OAuth or client-credentials flow for this API. Send the key on every request. A missing, revoked, or malformed key returns `401`. A valid key without the required permission, or an account whose plan no longer includes Integrations, returns `403`.

### What a key can call

| Permission | Scope | Route |
| --- | --- | --- |
| Read services and prices | `catalog:view` | `GET /api/servicecategories` |
| Check availability | `availability:read` | `GET /api/Appointments/availability` |
| Create a client | `clients:create` | `POST /api/Clients` |
| Read clients | `clients:view` | `GET /api/Clients/search`, `GET /api/Clients/{id}` |
| Create an appointment | `appointments:create` | `POST /api/Appointments` |
| Read appointments | `appointments:read` | `GET /api/Appointments/search`, `GET /api/Appointments/{id}` |
| Reschedule | `appointments:edit` | `POST /api/Appointments/{id}/reschedule` |
| Cancel | `appointments:cancel` | `POST /api/Appointments/{id}` |

Everything else returns `403`. A key cannot reach sales, reports, payments, team management, settings, or the API-key admin routes. No key can mint another key.

Keep the key on a server you control. Never put it in a visitor's browser.

A Swagger UI is reachable on https://api.bellabooking.com. It lists dashboard routes as well as the nine above. **API keys cannot call those dashboard routes.** The documented surface is the table in this file and the api-keys docs, not the full Swagger list.

## 2. Public docs MCP (no auth)

| | |
| --- | --- |
| Card on this host | https://bellabooking.com/.well-known/mcp/server-card.json |
| Transport | https://docs.bellabooking.com/mcp |
| Authentication | none |

This server searches product documentation. It does not create appointments, read a business's data, or accept an API key. Mintlify also publishes a card at https://docs.bellabooking.com/.well-known/mcp/server-card.json; fetch the same-origin card on this host.

## 3. Business MCP (managed)

Bella AI and the business MCP are scoped to one account. Access is set up per business after a conversation. See https://bellabooking.com/developers. It is **not** a one-click public connector.

The platform MCP credential used by Bella's own assistants is first-party only and is never issued to a customer. Do not expect `tools/call` on any public Bella MCP URL to book an appointment.

## 4. Human login (not for the public API)

Business team members sign in to the dashboard at https://app.bellabooking.com. OpenID Provider: https://auth.bellabooking.com (discovery: https://auth.bellabooking.com/.well-known/openid-configuration).

Clients signing in on a booking page use a **separate** issuer: https://book-bellabooking.au.auth0.com. A third-party website cannot mint those sessions. To book from the business's own site, use the website-booking API key in section 1.

## 5. What does not exist

- No public, unauthenticated "book an appointment" MCP.
- No OAuth / M2M token for the website-booking API.
- No OAuth Protected Resource metadata for https://api.bellabooking.com.
- No agent-initiated payment (x402, ACP, AP2). Deposits use the business's existing Stripe checkout.
- No WebMCP tools on this marketing site.

## See also

- Product corpus: https://bellabooking.com/llms.txt
- API catalog: https://bellabooking.com/.well-known/api-catalog
- Agent skill: https://bellabooking.com/.well-known/agent-skills/index.json