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 — credential exchange → access + refresh tokens
• POST /api/v1/user/register — account creation (platform/e2e surface)
• POST /api/v1/auth/validate — refresh-token rotation
• POST /api/v1/user/s/logout — server-side session revocation

Game SDK

• POST /api/v1/game-sdk//sessions — issue a single-use match session
• POST /api/v1/game-sdk//results — submit a result claim

Secure purchases (SDK-mediated)

• POST /api/v1/security/pin-session — mint a one-time PIN session
• POST /api/v1/security/pin-session//verify — verify the PIN (single-shot)
• POST /api/v1/security/events — 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

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.

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

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.