> ## 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. # Authenticate a player > Exchanges player credentials for an access token and a refresh token. The response is camelCase on the wire. The SDK derives its session expiry from `expiresIn` (seconds) and from JWT `exp` claims when present. Token signatures are never verified by the client — the backend is the identity owner. When `requiresOTP` is `true`, the SDK surfaces an `AuthenticationFailed` error because OTP verification is not yet supported by the client runtime. ## OpenAPI ````yaml /openapi/musterbox-public.yaml post /api/v1/user/login openapi: 3.0.3 info: title: MusterBox Public API version: 1.0.0 description: | The public surface of the MusterBox developer platform. Every path in this document is verified against the MusterBox backend source code. The client SDK (`MusterBoxSdk`) is the recommended way to drive these endpoints; these pages document the wire contract for teams that need to understand or debug the traffic the SDK produces. Environments are selected by the base URL. The control-plane base URL per environment is: | Environment | Base URL | | ------------ | --------------------------------- | | `local` | `http://localhost:8081` | | `sandbox` | `https://sandbox-api.musterbox.dev` | | `staging` | `https://staging-api.musterbox.dev` | | `production` | `https://api.musterbox.com` | All paths below include the `api/v1` backend prefix explicitly, matching how the SDK resolves URLs (`control plane base` + `/api/v1`). > **Security boundary**: authentication, game sessions and results are the > only integration surfaces. Purchase endpoints exist for the on-device > PIN-verification flow and should always be driven through the SDK's > `PurchaseClient` — never hand-rolled. Do not roll your own purchase flow. servers: - url: https://api.musterbox.com description: Production (default) - url: https://sandbox-api.musterbox.dev description: Sandbox — pre-production validation - url: https://staging-api.musterbox.dev description: Staging — pre-release integration environment - url: http://localhost:8081 description: Local development backend security: - bearerAuth: [] tags: - name: Authentication description: Player login, session refresh, and logout via the backend auth API - name: Game SDK description: >- Match sessions and mutually-confirmed results for games hosted by MusterBox - name: Secure purchases description: SDK-mediated PIN sessions for secure player purchases paths: /api/v1/user/login: post: tags: - Authentication summary: Authenticate a player description: | Exchanges player credentials for an access token and a refresh token. The response is camelCase on the wire. The SDK derives its session expiry from `expiresIn` (seconds) and from JWT `exp` claims when present. Token signatures are never verified by the client — the backend is the identity owner. When `requiresOTP` is `true`, the SDK surfaces an `AuthenticationFailed` error because OTP verification is not yet supported by the client runtime. operationId: login requestBody: required: true content: application/json: schema: type: object required: - identifier - password properties: identifier: type: string description: Player email address or handle. example: player@example.com password: type: string description: Player password. example: '********' oneClick: type: boolean description: Request a one-click style login session where supported. device_id: type: string description: >- Caller-supplied device identifier (also sent as the `x-device-id` header). device_name: type: string description: Human-readable device name. device_os: type: string description: Device operating system name. location: type: string description: Free-form location string reported by the client. responses: '200': description: Successful credential exchange. content: application/json: schema: $ref: '#/components/schemas/LoginResponse' '400': description: Malformed request or invalid credential format. content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Invalid credentials. content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ApiError' components: schemas: LoginResponse: type: object properties: message: type: string description: Optional backend message (for example "Login successful"). accessToken: type: string description: Bearer access token. refreshToken: type: string description: Refresh token for `/auth/validate` rotation. expiresIn: type: integer format: int64 description: Access-token lifetime in seconds. example: 3600 user: type: object additionalProperties: true description: Backend user object. requiresOTP: type: boolean default: false description: >- Whether the backend requires further OTP verification. The SDK surfaces an error when true. required: - accessToken - refreshToken - expiresIn - user ApiError: type: object description: >- NestJS error envelope ({ error: { code, message, status } }) or the plain { message } shape. properties: error: type: object properties: code: type: string message: type: string status: type: integer message: type: string securitySchemes: bearerAuth: type: http scheme: bearer description: Player access token returned by login/refresh. ````