openapi: 3.0.3
info:
  title: Mobile Check Cashing SDK — Authenticate OBO
  version: '1'
  description: |
    **Required for Card Partners.** Binds the partner session (obtained
    via `POST /api/v1/partners/authenticate`) to a specific customer and
    returns a one-time-use `ssoToken`. **PayPal partners do not call this
    endpoint** — `POST /api/v1/paypal/customers/register` already binds
    the session and returns the `ssoToken`.

    For **Card partners** the OBO call is **not optional** — it must
    complete before invoking any customer-scoped partner method
    (`get-registered-cards`, `add-or-update-card`,
    `get-transaction-history`, `add-session-attributes`, etc.) or
    before launching the SDK on the device. **PayPal partners skip it**
    — `register-customer` performs the binding for them.

    **Card partner call order.**
    1. Obtain OAuth 2.0 bearer token (scope `sdkapi`).
    2. `POST /authenticate` → capture `SessionId` response header.
    3. `POST /find-customer` or `POST /enroll-customer` → obtain
       `customerId`.
    4. **`POST /authenticate-obo`** → obtain `ssoToken`. *Last
       mandatory call.*
    5. Optional partner methods may follow.

    **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`.
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: Bind the partner session to a specific customer for SDK initialization.
paths:
  /api/v1/partners/authenticate-obo:
    post:
      tags:
        - Session Authentication
      operationId: authenticateOBO
      summary: Bind the partner session to a customer
      description: |
        **Required.** Final mandatory step in the SDK partner
        integration flow. Binds the partner session to a specific
        customer (`customerId`) and must complete successfully before
        SDK initialization or any other partner method call after
        `/authenticate`.

        Returns a single-use `ssoToken` to pass into the mobile SDK at
        initialization time.
      parameters:
        - $ref: '#/components/parameters/SessionIdHeader'
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateOboRequest'
            example:
              customerId: 333554bf-b273-4d6e-b4f8-d319a1929608
      responses:
        '200':
          description: Customer authenticated. Use `ssoToken` to initialize the SDK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticateOboResponse'
              example:
                ssoToken: >-
                  NjI4NWRlNzYtOTYxNC00Y2MyLWE3MjctMGYyN2E2NTRhZmQxOmI4M2E3NWQzLWU0MDYtNGMyYi04ZjA1LWU3YzlhNDcwMzNhBQ==
        '422':
          description: |
            Customer not found, or the customer has no linked account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                customerNotFound:
                  summary: Customer not found
                  value:
                    type: https://tools.ietf.org/html/rfc4918#section-11.2
                    title: Customer Not Found
                    status: 422
                    detail: >-
                      Oops, your customer information does not exist in our
                      service. Please check your login and try again. (A45)
                    instance: /api/v1/partners/authenticate-obo
                    errorCode: CUSTOMER_NOT_FOUND
                noLinkedAccount:
                  summary: No linked account
                  value:
                    type: https://tools.ietf.org/html/rfc4918#section-11.2
                    title: No linked account
                    status: 422
                    detail: The customer does not have a linked account.
                    instance: /api/v1/partners/authenticate-obo
                    errorCode: NO_LINKED_ACCOUNT
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
  parameters:
    SessionIdHeader:
      name: SessionId
      in: header
      required: true
      schema:
        type: string
      description: |
        Session identifier returned in the `SessionId` response header
        of `POST /api/v1/partners/authenticate`.
    DeviceIdHeader:
      name: DeviceId
      in: header
      required: true
      schema:
        type: string
      description: |
        iovation BlackBox device identifier. Per the Card Partners
        Methods page, `DeviceId` must accompany every partner-method
        request after `/authenticate`.
  schemas:
    AuthenticateOboRequest:
      type: object
      required:
        - customerId
      properties:
        customerId:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
          description: Ingo-assigned customer identifier (GUID).
    AuthenticateOboResponse:
      type: object
      required:
        - ssoToken
      properties:
        ssoToken:
          type: string
          description: |
            Single-use SSO token. Pass to the mobile SDK at
            initialization. Treat as a credential — do not log or
            store beyond the session.
    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.