> ## 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.

# Verify a submitted PIN (single-shot)

> Verifies the PIN the player entered against the minted one-time
session. **Single-shot and never retried**: the backend consumes
sessions on success and rate-limits failures.

The `x-secure-session` header carries the `sessionToken` from the mint
response. When `valid` is `true`, the response payload is the full
backend verify response; a non-`valid` response reports `locked` and
the attempt counter.




## OpenAPI

````yaml /openapi/musterbox-public.yaml post /api/v1/security/pin-session/{id}/verify
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/security/pin-session/{id}/verify:
    post:
      tags:
        - Secure purchases
      summary: Verify a submitted PIN (single-shot)
      description: |
        Verifies the PIN the player entered against the minted one-time
        session. **Single-shot and never retried**: the backend consumes
        sessions on success and rate-limits failures.

        The `x-secure-session` header carries the `sessionToken` from the mint
        response. When `valid` is `true`, the response payload is the full
        backend verify response; a non-`valid` response reports `locked` and
        the attempt counter.
      operationId: verifyPin
      parameters:
        - name: id
          in: path
          required: true
          description: The `sessionId` returned by mint.
          schema:
            type: string
          example: 7c1f9a2e-4b6d-4c8e-b1a0-1e2d3c4b5a6f
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pin
                - amount
                - destinationAddress
                - idempotencyKey
              properties:
                pin:
                  type: string
                  description: The PIN the player entered.
                  example: '482915'
                amount:
                  type: string
                  description: The authorized amount as a decimal string.
                  example: '9.99'
                destinationAddress:
                  type: string
                  description: Wallet destination the player is authorizing.
                  example: 9.78200031609046e+47
                idempotencyKey:
                  type: string
                  description: Client-generated key scoping one authorized withdrawal.
                  example: buy-arena-bundle-8f3b
      responses:
        '200':
          description: >-
            Verification outcome (`valid` true or false with lock/attempt
            details).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PinVerifyResponse'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '410':
          description: One-time session expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: PIN attempt limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth: []
        - secureSession: []
components:
  schemas:
    PinVerifyResponse:
      type: object
      properties:
        valid:
          type: boolean
          description: >-
            Whether the PIN was accepted. When true the object also carries the
            full backend verify payload.
        locked:
          type: boolean
          description: Whether the session is now rate-limited after the failure.
        attempt:
          type: integer
          description: Failure attempt counter.
    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.
    secureSession:
      type: apiKey
      in: header
      name: x-secure-session
      description: One-time session token from the mint response.

````