# Sessions Go — agent guide

You are working against the Sessions Go public API on behalf of a developer or end user. This document teaches you what's available and how to use it correctly.

## Surface

- **GraphQL endpoint**: `https://go.sessions.website/api/graphql` — POST or GET, CORS open, introspection enabled.
- **Embeddable web components**: served from `https://go.sessions.website/embeds/unstable/<name>.js`. Six are published — `<sessions-schedule>`, `<sessions-products>`, `<sessions-reservations>`, `<sessions-account>`, `<sessions-active-products>`, `<sessions-user>`. Drop a `<script type="module">` tag and the corresponding custom element on the host page; styling lives inside the embed's Shadow DOM.
- **Reference docs**: `https://go.sessions.website/build` (humans) / `https://go.sessions.website/build/agents/llms-full.txt` (you).
- **Claude Code plugin**: `claude plugin marketplace add SessionsCode/ai-toolbox` then `claude plugin install sessions@ai-toolbox` — installs skills for the public and business APIs with full schema references, auto-updating with the deployed schema.
- **MCP servers** (Streamable HTTP; connection config at `https://go.sessions.website/build/agents/mcp.json`):
  - `https://go.sessions.website/build/api/mcp` — **sessions-dev** (no auth): search the schema (`search_docs`), look up a type/operation (`get_type`, `get_operation`), and validate a GraphQL document (`validate_graphql`).
  - `https://go.sessions.website/api/mcp` — **sessions-public**: task-shaped tools (find a business, browse the schedule, preview checkout, start sign-in, view/cancel registrations). Discovery is anonymous; viewer tools use the `auth` cookie or a Bearer JWT. Also mounted handle-scoped at `https://go.sessions.website/@<handle>/api/mcp`.
  - `https://business.sessions.website/@<handle>/api/mcp` — **sessions-business**: staff/owner tools (list activities, upcoming sessions, attendance, stats, and create/cancel sessions), pinned to one business. Always authenticated; field access follows your staff role. Unauthenticated requests get the MCP OAuth challenge (`401` + `WWW-Authenticate`) pointing at `/.well-known/oauth-protected-resource`.

## Authentication

Two modes:
1. **`auth` cookie** — set automatically when the user signs in via the Sessions web app. Use `credentials: 'include'` when calling from a same-site context.
2. **Bearer JWT** — `Authorization: Bearer <jwt>`. Embed-scoped tokens are issued by the business-pinned sign-in flow (`createAccount` / `signIn` with `businessHandle` set).

For the **MCP servers**, an OAuth flow issues a Bearer access token (start from the `401` + `WWW-Authenticate` challenge / the `/.well-known/oauth-protected-resource` document). MCP clients self-register a public, PKCE-only client via Dynamic Client Registration (`POST /oauth/register`, advertised in `/.well-known/oauth-authorization-server`), then run the authorization-code flow. The MCP scopes are `mcp:business` (staff access to one business, bounded by your real staff role) and `mcp:account` (your own account + registrations). These resolve to your first-party user — distinct from the partner API-key scopes, which only reach the restricted external surface.

There is no separate "personal access token" concept. Without a token, ask the user to sign in to Sessions in their browser (the cookie rides along on same-site requests) or to complete the MCP OAuth flow.

## Conventions

- IDs are global IDs (opaque base64 strings). Pass them through verbatim.
- List queries follow the cursor pagination shape: `first` / `after` / `{nodes, pageInfo {hasNextPage, endCursor}}`.
- Mutations that mutate viewer state (registrations, purchases) return per-field validation errors instead of throwing — check the result shape before treating an operation as successful.
- Mutations that send email (`signIn`, `createAccount`) always succeed regardless of whether the email matches an account. This is anti-enumeration, not a bug.

## Do

- Use `checkoutPreview` to compute totals before triggering a payment.
- Honor `deprecationReason` on fields you see in introspection or the reference; switch to the documented replacement.
- Cache `services` and other static metadata for the lifetime of your session.

## Don't

- Don't paste a Bearer token into a request that already has the `auth` cookie — pick one auth path per request.
- Don't assume embed JWTs work across businesses. Each token is scoped to one business handle.
- Don't poll for state changes — there's no rate limiter today, but server-side request budgets are real. Re-query on user-driven actions.

## When stuck

- Read `https://go.sessions.website/build/agents/llms-full.txt` for the full schema and embed reference in one document.
- Introspect: `{ __schema { types { name kind } } }` against the endpoint will always work.
- Ask the developer to open `https://go.sessions.website/build/graphql/public/reference` and link you to the relevant type page.