openapi: 3.0.3
info:
  title: Cardholder Auth API
  description: OpenAPI definition file for Cardholder Authentication API
  termsOfService: https://www.marqeta.com/api-terms
  version: 1.0.0
  contact:
    name: Marqeta
    email: support@marqeta.com
servers:
  - url: /api/v1
tags:
  - name: cardholder-auth
paths:
  /oauth/token:
    post:
      operationId: postOauthToken
      tags:
        - oauth-token
      summary: Generate UX Toolkit OAuth authentication token
      description: >-
        Use this endpoint to generate your UX Toolkit OAuth authentication
        token.

        This token enables access to the specified account to pass it back to
        the UX Toolkit client.

        For details, see UX Toolkit Getting Started
        (https://www.marqeta.com/test-docs/developer-guides/uxt-getting-started/).
      parameters:
        - name: DPoP
          in: header
          description: DPoP proof JWT for OAuth-bound access token
          required: true
          schema:
            type: string
      security:
        - CardholderAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              example:
                access_token: >-
                  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwcm9ncmFtX3Nob3J0X2NvZGUiOiJteXByZ3JtIiwidXNlcl90b2tlbiI6IjE0OWNjYjVmLWUwZDYtNGMwZS05MjAzLWJkMDkyZGI0N2UzNCJ9.6TdyvMOa_eUSvN5GpUZKBOgcHxmWTuYQPMEgNwBfVS0
                expires_in: 3600
                token_type: DPoP
              schema:
                $ref: '#/components/schemas/PostOauthTokenResponse'
        default:
          description: User input error/Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorStandardizedObject'
components:
  securitySchemes:
    CardholderAuth:
      type: apiKey
      in: cookie
      name: JSESSIONID
  schemas:
    PostOauthTokenResponse:
      properties:
        access_token:
          description: >-
            DPoP-bound JWT that must be passed back to UX Toolkit client via
            your Customer Authentication API.
          type: string
        expires_in:
          description: >-
            Number of seconds for which the returned `access_token` will remain
            valid.
          type: number
        token_type:
          description: |-
            Identifies the token type.
            For DPoP flows, this value is always `DPoP`.
          enum:
            - DPoP
      required:
        - access_token
        - expires_in
        - token_type
      type: object
    ErrorStandardizedObject:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorIdObject'
      required:
        - error
    ErrorIdObject:
      type: object
      properties:
        id:
          description: Unique identifier of the type of error.
          type: string
        debug:
          description: List of underlying errors or issues.
          items:
            $ref: '#/components/schemas/ErrorDebugItem'
          type: array
      required:
        - id
        - debug
    ErrorDebugItem:
      type: object
      properties:
        source:
          description: Unique identifier of the source service where the error originated.
          type: string
        code:
          description: Code string of the specific type of error.
          type: string
        message:
          description: Message providing additional information about the error.
          type: string
      required:
        - source
        - message