Skip to content
Authentication

There’s no user session — a key authenticates the request on its own.

  • API key

    — send your key in the `Authorization` header as a Bearer token

  • Bound to one business

    — a key only works on its own business’s handle endpoint; presenting it elsewhere is refused

  • HTTPS only

    — keys are accepted only over HTTPS and never fall back to a user session
curl https://business.sessions.website/@<handle>/api/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_live_…' \
  --data '{"query":"{ activeBusiness { id name } }"}'

Create and manage keys in the business admin under Settings → API keys: name a key, grant it scopes, and copy its secret once at creation. Treat the secret like a password — store it server-side and rotate it if it leaks.

Scopes

A key is granted one or more scopes. A request that touches a field outside its scopes is refused. Scopes available today:

participants:read

Read participants — name, email, and marketing-consent state.

registrations:read

Read activity registrations and their status.

products:read

Read the products a business sells.

purchases:read

Read product purchases — passes, memberships, gift cards, and physical goods.

webhooks:read

Read the business’s webhook endpoints and their delivery history.

webhooks:write

Create, update, and remove webhook endpoints.

Effective access is the intersection of a key’s scopes and the business’s own grants — a scope a key holds but the business doesn’t have still resolves to nothing.

MCP server (AI assistants)

The business MCP server lets an AI assistant act as you — the signed-in staff member — rather than as a partner integration. It runs the same tools a staffer would (list activities, upcoming sessions, attendance, create/cancel sessions), over the Model Context Protocol.

  • Endpoint

    — a Streamable-HTTP MCP endpoint at your handle, /@<handle>/api/mcp. An unauthenticated request returns 401 with a WWW-Authenticate challenge that points at /.well-known/oauth-protected-resource — the OAuth discovery document.

  • OAuth flow

    — the client self-registers via Dynamic Client Registration (RFC 7591, POST /oauth/register), you approve it on the consent screen and choose the business, and it receives an access token. Registered MCP clients are public, so they must use PKCE.

  • Scope

    — mcp:business resolves the token to your user with your real staff permissions on that business — the token is an access path, never an escalation, and the business schema still enforces your role. This is separate from the partner API-key scopes above, which only reach the restricted external surface.
# 1. An unauthenticated MCP request is challenged:
#    HTTP/1.1 401 Unauthorized
#    WWW-Authenticate: Bearer resource_metadata="https://business.sessions.website/.well-known/oauth-protected-resource"

# 2. The client discovers the authorization server, registers, and the
#    user consents — it then calls the MCP server with the token:
curl https://business.sessions.website/@<handle>/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <mcp-access-token>' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call",
           "params":{"name":"upcoming_sessions","arguments":{}}}'

Consumer (end-user) access to the public API over MCP uses the mcp:account scope on the public server — see the public API authentication guide.

Authentication