openapi: 3.2.0
info:
  title: Open Finance Customer Authorization Details API
  description: 'OpenAPI specification for Finicity APIs.


    Open Finance (formerly Open Banking) solutions in the US are provided by

    Finicity, a Mastercard company.'
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/open-finance-us/documentation/support/
  version: 1.43.0
servers:
- url: https://api.finicity.com
  description: Production
security:
- FinicityAppKey: []
  FinicityAppToken: []
tags:
- name: Customer Authorization Details
  description: APIs to retrieve customer authorization details
paths:
  /customers/institution-logins/{institution_login_id}/authorization-details:
    get:
      tags:
      - Customer Authorization Details
      summary: Get Customer Authorization Details
      description: 'Retrieve the start date and end date of Data Connect authorization granted by a customer for a specific financial institution.


        Requires the customer''s `institutionLoginId`.


        Note: details can only be retrieved for authorizations granted via an OAuth connection. If authorization was granted via a legacy connection, the endpoint returns error code 3003.


        Note: if authorization was granted before this endpoint was introduced, authorization details may be unavailable (error code 3004).


        _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)'
      parameters:
      - $ref: '#/components/parameters/InstitutionLoginIdPathParam'
      responses:
        '200':
          $ref: '#/components/responses/CustomerAuthorizationDetails'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '404':
          $ref: '#/components/responses/GetCustomerAuthorizationDetailsNotFoundErrorResponse'
      operationId: getCustomerAuthorizationDetails
components:
  examples:
    MissingFinicityAppKeyExample:
      value:
        code: '10026'
        message: Missing parameter (Finicity-App-Key)
    InstitutionLoginIdNotFoundErrorResponseExample:
      value:
        code: '3003'
        status: '404'
        message: Resource Not Found.
        user_message: Institution Login Id is not found
    InstitutionLoginIdDetailsNotFoundErrorResponseExample:
      value:
        code: '3004'
        status: '404'
        message: Resource Not Found.
        user_message: Institution Login Id details are not found
    ExpiredFinicityAppTokenExample:
      value:
        code: '10023'
        message: Expired (Finicity-App-Token)
    ExpiredTokenExample:
      value:
        code: '10023'
        message: Expired (Finicity-App-Token)
    InvalidFinicityAppTokenExample:
      value:
        code: '10022'
        message: Invalid (Finicity-App-Token)
    BadCredentialsExample:
      value:
        code: '24302'
        message: Bad credentials
    CustomerAuthorizationDetailsExample:
      value:
        institutionLoginId: 7008461438
        authorizationStartDate: 2024-01-01 16:11:23.200000+00:00
        authorizationEndDate: 2024-12-31 16:11:23.200000+00:00
    MissingFinicityAppTokenExample:
      value:
        code: '10024'
        message: Missing parameter (Finicity-App-Token)
  schemas:
    CustomerAuthorizationDetails:
      type: object
      properties:
        institutionLoginId:
          type: integer
          description: Institution login id of the customer.
          format: int64
          example: 7009561328
        authorizationStartDate:
          type: string
          description: Authorization start date and time in ISO 8601 format.
          example: 2024-01-01 16:11:23.200000+00:00
        authorizationEndDate:
          type: string
          description: Authorization end date and time in ISO 8601 format.
          example: 2024-12-31 16:11:23.200000+00:00
      required:
      - institutionLoginId
      - authorizationStartDate
      - authorizationEndDate
    AssetId:
      type: string
      description: An asset ID. Generated by Data Connect or by using the Store Customer Pay Statement API.
      example: 097545c5-1c2a-4f20-a5ef-77f0820344c9-2018601178
    ErrorMessage:
      required:
      - code
      type: object
      properties:
        code:
          type: object
          description: 'An error code (can be returned as a number or a string). Useful links: [Common API Status Codes](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/#common-api-status-codes), [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/#aggregation-status-codes).'
          example: '10001'
        status:
          type: string
          description: A status code
          example: '401'
        title:
          type: string
          description: A title for the error
          example: Connecting accounts error
        level:
          type: string
          description: An error level
          example: error
        message:
          type: string
          description: An error message
          example: Invalid authorization credentials
        user_message:
          type: string
          description: Some more details about the error
          example: The session has expired or is invalid
        assetId:
          $ref: '#/components/schemas/AssetId'
        accountId:
          $ref: '#/components/schemas/AccountId'
        externalTransactionId:
          type: string
          description: A unique identifier for the transaction that assists in linking data back to your systems.
          example: MAC1005061234
          minLength: 1
          maxLength: 100
        tags:
          type: string
          description: Categories that the error belongs to
          example: AGG
    AccountId:
      type: string
      description: An account ID
      example: '5011648377'
  responses:
    CustomerAuthorizationDetails:
      description: Successfully retrieved customer authorization details by institution login id.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CustomerAuthorizationDetails'
          examples:
            CustomerAuthorizationDetailsExample:
              $ref: '#/components/examples/CustomerAuthorizationDetailsExample'
    UnauthorizedErrorResponse:
      description: The request lacks valid authentication credentials. Check "Finicity-App-Key" or "Finicity-App-Token".
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            ExpiredTokenExample:
              $ref: '#/components/examples/ExpiredTokenExample'
            MissingFinicityAppKeyExample:
              $ref: '#/components/examples/MissingFinicityAppKeyExample'
            MissingFinicityAppTokenExample:
              $ref: '#/components/examples/MissingFinicityAppTokenExample'
            InvalidFinicityAppTokenExample:
              $ref: '#/components/examples/InvalidFinicityAppTokenExample'
            ExpiredFinicityAppTokenExample:
              $ref: '#/components/examples/ExpiredFinicityAppTokenExample'
            BadCredentialsExample:
              $ref: '#/components/examples/BadCredentialsExample'
        text/plain:
          schema:
            type: string
            example: Invalid (Finicity-App-Key)
    GetCustomerAuthorizationDetailsNotFoundErrorResponse:
      description: The resource doesn't exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            InstitutionLoginIdNotFoundErrorResponseExample:
              $ref: '#/components/examples/InstitutionLoginIdNotFoundErrorResponseExample'
            InstitutionLoginIdDetailsNotFoundErrorResponseExample:
              $ref: '#/components/examples/InstitutionLoginIdDetailsNotFoundErrorResponseExample'
  parameters:
    InstitutionLoginIdPathParam:
      name: institution_login_id
      description: Institution login id of the customer.
      in: path
      required: true
      schema:
        type: integer
        format: int64
        example: 7008461438
  securitySchemes:
    FinicityAppKey:
      name: Finicity-App-Key
      type: apiKey
      in: header
      description: The "Finicity-App-Key" from the developer dashboard
    FinicityAppToken:
      name: Finicity-App-Token
      type: apiKey
      in: header
      description: A token returned by the `/authentication` API