> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musterbox.org/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> The MusterBox public API — authenticated player and game surfaces, verified against source.

This section documents the wire contract the MusterBox SDK drives. Every
endpoint here is **verified against the MusterBox backend source** — nothing
is speculative. Endpoints are grouped by purpose:

## Authentication

* [POST /api/v1/user/login](/api/api-overview) — credential exchange → access + refresh tokens
* [POST /api/v1/user/register](/api/api-overview) — account creation (platform/e2e surface)
* [POST /api/v1/auth/validate](/api/api-overview) — refresh-token rotation
* [POST /api/v1/user/s/logout](/api/api-overview) — server-side session revocation

## Game SDK

* [POST /api/v1/game-sdk/{gameId}/sessions](/api/api-overview) — issue a single-use match session
* [POST /api/v1/game-sdk/{gameId}/results](/api/api-overview) — submit a result claim

## Secure purchases (SDK-mediated)

* [POST /api/v1/security/pin-session](/api/api-overview) — mint a one-time PIN session
* [POST /api/v1/security/pin-session/{id}/verify](/api/api-overview) — verify the PIN (single-shot)
* [POST /api/v1/security/events](/api/api-overview) — best-effort security-event log

## Environments

| Environment  | Control-plane base                  |
| ------------ | ----------------------------------- |
| `local`      | `http://localhost:8081`             |
| `sandbox`    | `https://sandbox-api.musterbox.dev` |
| `staging`    | `https://staging-api.musterbox.dev` |
| `production` | `https://api.musterbox.com`         |

The OpenAPI document uses these as servers and writes every path with the
`/api/v1` prefix, exactly as the SDK resolves URLs
(`control-plane-base` + `/api/v1`).

## Authentication model

Every endpoint except register/login uses the **bearer access token** returned
from login. Game SDK routes additionally require the **`x-game-key`** header
(and results require the single-use **`x-session-token`**).

## Which clients should call the API directly?

| Surface                   | Recommended client                              |
| ------------------------- | ----------------------------------------------- |
| Authentication            | SDK (session, rotation, logout)                 |
| Game SDK sessions/results | SDK (`openSession` / `submitResult`)            |
| Secure purchases          | SDK only (`PurchaseClient`) — never hand-rolled |

<Warning>
  Purchase endpoints are SDK-mediated by design. Drive them through the SDK's
  `PurchaseClient` — never hand-roll a request, or you will skip the required
  environment pre-flight.
</Warning>

<Tip>
  The interactive playground on these pages lets you try requests against a
  server you configure. Use a **sandbox** server and test credentials.
</Tip>

<Note>
  The examples in the API pages assume an authenticated session. The easiest
  way to obtain tokens in a scratch environment is a player login against
  `sandbox` host.
</Note>