openapi: 3.0.3
info:
  title: Mobile Check Cashing SDK — Authenticate Partner
  version: '1'
  description: |
    First call in the Mobile Check Cashing SDK partner integration
    flow. Exchanges an OAuth 2.0 bearer token for a partner-level
    `sessionId` (returned as a response header) that authorizes every
    subsequent partner-method call.

    **Required call order.** After obtaining the OAuth bearer token,
    call `POST /authenticate` first. The resulting `sessionId` must
    accompany every other partner endpoint in the `SessionId` request
    header. Before initializing the SDK or invoking any
    customer-scoped endpoint (cards, transaction history, session
    attributes), the partner session must also be bound to a specific
    customer via `POST /authenticate-obo` — see the OBO note in the
    integration overview.

    **Authentication.** OAuth 2.0 client credentials grant. Token URLs:
    `https://auth.spykemobile.net/connect/token` (Production),
    `https://sandbox-auth.spykemobile.net/identity/connect/token`
    (UAT). Required scope: `sdkapi`. Tokens are valid for 3600 seconds.
servers:
  - url: https://check-cashing-uat.spykemobile.net
    description: UAT (Sandbox)
  - url: https://check-cashing.spykemobile.net
    description: Production
security:
  - OAuth2:
      - sdkapi
tags:
  - name: Session Authentication
    description: Bootstrap a partner-level SDK session.
paths:
  /api/v1/partners/authenticate:
    post:
      tags:
        - Session Authentication
      operationId: authenticatePartner
      summary: Authenticate the partner and obtain a session
      description: |
        Validates that the application has the right to connect to
        Ingo Money servers. On success, the `sessionId` is returned in
        the `SessionId` response header — capture it and include it on
        every subsequent partner-method call as the `SessionId`
        request header.

        This is the only SDK partner endpoint that does NOT require the
        `SessionId` or `DeviceId` request headers.
      responses:
        '200':
          description: |
            Partner authenticated. The `SessionId` response header
            contains the session identifier to use on all subsequent
            partner calls.
          headers:
            SessionId:
              schema:
                type: string
              description: |
                Session identifier. Pass on subsequent partner calls
                as the `SessionId` request header.
        '401':
          description: |
            Authorization failure. The bearer token is missing,
            expired, or not authorized for the `sdkapi` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc7235#section-3.1
                title: Unauthorized
                status: 401
                detail: Authorization has been denied for this request.
                instance: /api/v1/partners/authenticate
                errorCode: UNAUTHORIZED
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: |
        OAuth 2.0 client credentials grant. Production token URL is
        defined below. For UAT, use
        `https://sandbox-auth.spykemobile.net/identity/connect/token`
        instead. Tokens are valid for 3600 seconds.
      flows:
        clientCredentials:
          tokenUrl: https://auth.spykemobile.net/connect/token
          scopes:
            sdkapi: Mobile Check Cashing SDK partner methods
  schemas:
    ProblemDetails:
      type: object
      description: RFC 7807-style problem details envelope used for non-success responses.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        errorCode:
          type: string
          description: Stable machine-readable error code.