Mesh Self Managed Account Authentication API

openapi: 3.2.0
info:
  title: Mesh Connect Integration Assets Self Managed Account Authentication API
  description: '

    Mesh allows users to connect accounts of financial institutions,

    crypto exchanges, and self-custody wallets. Mesh handles credential

    validation, MFA, and error handling for each integration. After

    an account is connected, Mesh allows client applications to read holdings,

    transaction history and balances and execute crypto transfers (with user approval).'
  version: '1.0'
servers:
- url: https://integration-api.meshconnect.com
security:
- Client-Secret: []
  Client-Id: []
tags:
- name: Self Managed Account Authentication
  description: Not recommended approach. Using this approach, the API client is responsible for handling multiple authentication flows and supporting future updates and changes.
paths:
  /api/v1/authenticationSchemes:
    get:
      tags:
      - Self Managed Account Authentication
      summary: Get authentication schemes
      description: 'Get authentication schemes of available integrations to perform authentication programmatically (not using

        the Web Catalog UI).'
      responses:
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: {}
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrokerAuthenticationSchemeIReadOnlyCollectionApiResult'
              example:
                content:
                - brokerType: coinbasePro
                  authenticationSchemeType: apiKey
                  initialAuthenticationModel:
                    fields:
                    - name: Username
                      description: API key
                    - name: Password
                      description: Secret key
                    - name: AuthToken
                      description: Passphrase
                    - name: Type
                      description: CoinbasePro
                  mfaSchemes: []
                  instructionsUrl: https://help.coinbase.com/en/pro/other-topics/api/how-do-i-create-an-api-key-for-coinbase-pro
                status: ok
                message: ''
                errorType: ''
  /api/v1/authenticate:
    post:
      tags:
      - Self Managed Account Authentication
      summary: Authenticate user's account
      description: Authenticate user's brokerage/exchange account programmatically (not using the Web Catalog UI)
      parameters:
      - name: userId
        in: query
        description: Id of the end-user
        required: true
        schema:
          type: string
      requestBody:
        description: Authentication request.
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/B2BBrokerAuthRequest'
            example:
              username: username
              password: password
              mfaCode: '000000'
              mfaType: phone
              type: robinhood
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/B2BBrokerAuthResponseApiResult'
              example:
                content:
                  status: succeeded
                  expiresInSeconds: 7200
                  accountTokens:
                  - account:
                      meshAccountId: 00000000-0000-0000-0000-000000000000
                      frontAccountId: 00000000-0000-0000-0000-000000000000
                      accountId: Id of the account
                      accountName: Name of the account
                    accessToken: Access token, allowing access to the integration
                    refreshToken: Optional refresh token, allowing to refresh the access token
                status: ok
                message: ''
                errorType: ''
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server Error
        '503':
          description: Server Error
  /api/v1/authenticate/{brokerType}:
    get:
      tags:
      - Self Managed Account Authentication
      summary: Get OAuth authentication link
      description: Get OAuth link for the integrations with `OAuth` AuthenticationSchemeType
      parameters:
      - name: brokerType
        in: path
        description: Type of the integration to connect
        required: true
        schema:
          enum:
          - robinhood
          - eTrade
          - alpaca
          - tdAmeritrade
          - weBull
          - stash
          - interactiveBrokers
          - public
          - coinbase
          - kraken
          - coinbasePro
          - cryptoCom
          - openSea
          - binanceUs
          - gemini
          - cryptocurrencyAddress
          - cryptocurrencyWallet
          - okCoin
          - bittrex
          - kuCoin
          - etoro
          - cexIo
          - binanceInternational
          - bitstamp
          - gateIo
          - acorns
          - okx
          - bitFlyer
          - coinlist
          - huobi
          - bitfinex
          - deFiWallet
          - krakenDirect
          - vanguard
          - binanceInternationalDirect
          - bitfinexDirect
          - bybit
          - paxos
          - coinbasePrime
          allOf:
          - $ref: '#/components/schemas/BrokerType'
      - name: userId
        in: query
        description: Id of the end-user
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/B2BBrokerAuthPromptResponseApiResult'
              example:
                content:
                  status: redirect
                  redirectLink: https://web.meshconnect.com/broker-connect/callback
                  linkToken: Link to the integration's site
                status: ok
                message: ''
                errorType: ''
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    B2BBrokerAuthResponse:
      type: object
      properties:
        status:
          enum:
          - failed
          - challengeFailed
          - succeeded
          - challengeIssued
          - mfaRequired
          - openInBrokerModule
          - delayed
          - deviceConfirmationRequired
          - emailVerification
          - emailReceived
          - captchaChallenge
          - faceVerification
          allOf:
          - $ref: '#/components/schemas/BrokerAuthStatus'
          description: Status of the request
        mfaType:
          allOf:
          - $ref: '#/components/schemas/MfaType'
        authFlowStep:
          allOf:
          - $ref: '#/components/schemas/AuthFlowStep'
          description: The AuthFlowStep is used to determine which state the authentication is in, for initial requests without MFA verification the value should be LoginPassword and when calling with MFA code it should be MfaFlow (currently used for BinanceInternationalDirect only).
        qrCode:
          type:
          - string
          - 'null'
          description: Qr code used to scan and solve facial verification (currently used for BinanceInternationalDirect only).
        qrCodeLink:
          type:
          - string
          - 'null'
        challengeId:
          type:
          - string
          - 'null'
          description: Id of the challenge, relevant when the status is `ChallengeIssued`
        challengeText:
          type:
          - string
          - 'null'
        challengeExpiresInSeconds:
          type:
          - integer
          - 'null'
          description: Life span of the challenge
          format: int32
        errorMessage:
          type:
          - string
          - 'null'
        displayMessage:
          type:
          - string
          - 'null'
        accessToken:
          type:
          - string
          - 'null'
          deprecated: true
        refreshToken:
          type:
          - string
          - 'null'
          deprecated: true
        expiresInSeconds:
          type:
          - integer
          - 'null'
          format: int32
        refreshTokenExpiresInSeconds:
          type:
          - integer
          - 'null'
          format: int32
        account:
          allOf:
          - $ref: '#/components/schemas/BrokerAccount'
          deprecated: true
        brokerBrandInfo:
          allOf:
          - $ref: '#/components/schemas/BrokerBrandInfo'
        accountTokens:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/BrokerAccountTokens'
        requiresReauthentication:
          type:
          - boolean
          - 'null'
        email:
          type:
          - string
          - 'null'
        allocatedIPAddress:
          type:
          - string
          - 'null'
      additionalProperties: false
    BrokerAccountTokens:
      type: object
      properties:
        account:
          allOf:
          - $ref: '#/components/schemas/BrokerAccount'
        accessToken:
          type:
          - string
          - 'null'
        refreshToken:
          type:
          - string
          - 'null'
      additionalProperties: false
    AuthFlowStep:
      enum:
      - loginPassword
      - mfaFlow
      - faceVerification
      type: string
    B2BBrokerAuthRequest:
      required:
      - type
      type: object
      properties:
        type:
          enum:
          - robinhood
          - eTrade
          - alpaca
          - tdAmeritrade
          - weBull
          - stash
          - interactiveBrokers
          - public
          - coinbase
          - kraken
          - coinbasePro
          - cryptoCom
          - openSea
          - binanceUs
          - gemini
          - cryptocurrencyAddress
          - cryptocurrencyWallet
          - okCoin
          - bittrex
          - kuCoin
          - etoro
          - cexIo
          - binanceInternational
          - bitstamp
          - gateIo
          - acorns
          - okx
          - bitFlyer
          - coinlist
          - huobi
          - bitfinex
          - deFiWallet
          - krakenDirect
          - vanguard
          - binanceInternationalDirect
          - bitfinexDirect
          - bybit
          - paxos
          - coinbasePrime
          allOf:
          - $ref: '#/components/schemas/BrokerType'
        phone:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        password:
          type:
          - string
          - 'null'
        tradePin:
          type:
          - string
          - 'null'
        countryInfo:
          allOf:
          - $ref: '#/components/schemas/CountryInfo'
        challengeId:
          type:
          - string
          - 'null'
        challengeCode:
          type:
          - string
          - 'null'
        challengeAnswer:
          type:
          - string
          - 'null'
          description: Used to provide answers to security questions
        mfaCode:
          type:
          - string
          - 'null'
        mfaType:
          enum:
          - phone
          - email
          - totp
          - phoneAndEmail
          - requireNextSecurityQuestion
          - readEmail
          - face
          allOf:
          - $ref: '#/components/schemas/MfaType'
        deviceInfo:
          type:
          - string
          - 'null'
        authFlowStep:
          allOf:
          - $ref: '#/components/schemas/AuthFlowStep'
        key:
          type:
          - string
          - 'null'
        authToken:
          type:
          - string
          - 'null'
        redirectLink:
          type:
          - string
          - 'null'
        confirmationEmail:
          type:
          - string
          - 'null'
      additionalProperties: false
    BrokerAuthStatus:
      enum:
      - failed
      - challengeFailed
      - succeeded
      - challengeIssued
      - mfaRequired
      - openInBrokerModule
      - delayed
      - deviceConfirmationRequired
      - emailVerification
      - emailReceived
      - captchaChallenge
      - faceVerification
      type: string
    B2BBrokerAuthPromptResponse:
      type: object
      properties:
        status:
          enum:
          - failed
          - redirect
          - openInBrokerModule
          allOf:
          - $ref: '#/components/schemas/BrokerAuthPromptStatus'
        redirectLink:
          type:
          - string
          - 'null'
        linkToken:
          type:
          - string
          - 'null'
        oAuthToken:
          type:
          - string
          - 'null'
        errorMessage:
          type:
          - string
          - 'null'
        displayMessage:
          type:
          - string
          - 'null'
      additionalProperties: false
    MfaType:
      enum:
      - phone
      - email
      - totp
      - phoneAndEmail
      - requireNextSecurityQuestion
      - readEmail
      - face
      type: string
    B2BBrokerAuthResponseApiResult:
      type: object
      properties:
        status:
          enum:
          - ok
          - serverFailure
          - permissionDenied
          - badRequest
          - notFound
          - conflict
          - tooManyRequest
          - locked
          allOf:
          - $ref: '#/components/schemas/ApiResultStatus'
          readOnly: true
        message:
          type:
          - string
          - 'null'
          description: A message generated by the API
        displayMessage:
          type:
          - string
          - 'null'
          description: User-friendly display message that can be presented to the end user
        errorType:
          type:
          - string
          - 'null'
          description: 'Strictly-typed error type that is explaining the reason of an unsuccessful status of the operation.

            All possible error types are available in the documentation.'
        errorData:
          readOnly: true
        content:
          allOf:
          - $ref: '#/components/schemas/B2BBrokerAuthResponse'
      additionalProperties: false
    BrokerAuthenticationSchemeIReadOnlyCollectionApiResult:
      type: object
      properties:
        status:
          enum:
          - ok
          - serverFailure
          - permissionDenied
          - badRequest
          - notFound
          - conflict
          - tooManyRequest
          - locked
          allOf:
          - $ref: '#/components/schemas/ApiResultStatus'
          readOnly: true
        message:
          type:
          - string
          - 'null'
          description: A message generated by the API
        displayMessage:
          type:
          - string
          - 'null'
          description: User-friendly display message that can be presented to the end user
        errorType:
          type:
          - string
          - 'null'
          description: 'Strictly-typed error type that is explaining the reason of an unsuccessful status of the operation.

            All possible error types are available in the documentation.'
        errorData:
          readOnly: true
        content:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/BrokerAuthenticationScheme'
      additionalProperties: false
    CountryInfo:
      type: object
      properties:
        countryCode:
          type:
          - string
          - 'null'
        countryNumber:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
      additionalProperties: false
    BrokerBrandInfo:
      type: object
      properties:
        brokerLogo:
          type:
          - string
          - 'null'
        brokerPrimaryColor:
          type:
          - string
          - 'null'
      additionalProperties: false
    MfaScheme:
      enum:
      - mfaCode
      - challenge
      - deviceConfirmation
      - securityQuestion
      type: string
    BrokerType:
      enum:
      - robinhood
      - eTrade
      - alpaca
      - tdAmeritrade
      - weBull
      - stash
      - interactiveBrokers
      - public
      - coinbase
      - kraken
      - coinbasePro
      - cryptoCom
      - openSea
      - binanceUs
      - gemini
      - cryptocurrencyAddress
      - cryptocurrencyWallet
      - okCoin
      - bittrex
      - kuCoin
      - etoro
      - cexIo
      - binanceInternational
      - bitstamp
      - gateIo
      - acorns
      - okx
      - bitFlyer
      - coinlist
      - huobi
      - bitfinex
      - deFiWallet
      - krakenDirect
      - vanguard
      - binanceInternationalDirect
      - bitfinexDirect
      - bybit
      - paxos
      - coinbasePrime
      type: string
    AuthenticationFieldDescription:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          description: Name of the field, as expected from the API
        description:
          type:
          - string
          - 'null'
      additionalProperties: false
    BrokerAccount:
      type: object
      properties:
        meshAccountId:
          type: string
          format: uuid
        frontAccountId:
          type: string
          format: uuid
          readOnly: true
          deprecated: true
        accountId:
          type:
          - string
          - 'null'
        accountName:
          type:
          - string
          - 'null'
        fund:
          type:
          - number
          - 'null'
          description: 'Buying power of the account. Typically consists of cash plus available margin.

            For non-margin accounts fund contains cash only'
          format: double
        cash:
          type:
          - number
          - 'null'
          description: Cash balance in USD
          format: double
        isReconnected:
          type:
          - boolean
          - 'null'
          description: 'Indicates if this account was already connected by the current user and device.

            Can be null.'
        balances:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/BrokerFiatBalance'
          description: The list of all asset balances of account
      additionalProperties: false
    BrokerFiatBalance:
      type: object
      properties:
        symbol:
          type:
          - string
          - 'null'
          description: Account balance currency
        buyingPower:
          type:
          - number
          - 'null'
          description: 'BuyingPower indicates total amount of money the user can spend for buying stock. Always includes cash and

            can also include margin'
          format: double
        cryptoBuyingPower:
          type:
          - number
          - 'null'
          description: BuyingPower indicates total amount of money the user can spend for buying crypto.
          format: double
        cash:
          type:
          - number
          - 'null'
          description: Account cash indicates total amount of money
          format: double
      additionalProperties: false
    AuthenticationSchemeType:
      enum:
      - usernamePassword
      - oAuth
      - apiKey
      - blockchainAddress
      type: string
    B2BBrokerAuthPromptResponseApiResult:
      type: object
      properties:
        status:
          enum:
          - ok
          - serverFailure
          - permissionDenied
          - badRequest
          - notFound
          - conflict
          - tooManyRequest
          - locked
          allOf:
          - $ref: '#/components/schemas/ApiResultStatus'
          readOnly: true
        message:
          type:
          - string
          - 'null'
          description: A message generated by the API
        displayMessage:
          type:
          - string
          - 'null'
          description: User-friendly display message that can be presented to the end user
        errorType:
          type:
          - string
          - 'null'
          description: 'Strictly-typed error type that is explaining the reason of an unsuccessful status of the operation.

            All possible error types are available in the documentation.'
        errorData:
          readOnly: true
        content:
          allOf:
          - $ref: '#/components/schemas/B2BBrokerAuthPromptResponse'
      additionalProperties: false
    BrokerAuthPromptStatus:
      enum:
      - failed
      - redirect
      - openInBrokerModule
      type: string
    BrokerAuthenticationScheme:
      type: object
      properties:
        brokerType:
          enum:
          - robinhood
          - eTrade
          - alpaca
          - tdAmeritrade
          - weBull
          - stash
          - interactiveBrokers
          - public
          - coinbase
          - kraken
          - coinbasePro
          - cryptoCom
          - openSea
          - binanceUs
          - gemini
          - cryptocurrencyAddress
          - cryptocurrencyWallet
          - okCoin
          - bittrex
          - kuCoin
          - etoro
          - cexIo
          - binanceInternational
          - bitstamp
          - gateIo
          - acorns
          - okx
          - bitFlyer
          - coinlist
          - huobi
          - bitfinex
          - deFiWallet
          - krakenDirect
          - vanguard
          - binanceInternationalDirect
          - bitfinexDirect
          - bybit
          - paxos
          - coinbasePrime
          allOf:
          - $ref: '#/components/schemas/BrokerType'
        authenticationSchemeType:
          enum:
          - usernamePassword
          - oAuth
          - apiKey
          - blockchainAddress
          allOf:
          - $ref: '#/components/schemas/AuthenticationSchemeType'
          description: Type of authentication for the integration.
        initialAuthenticationModel:
          allOf:
          - $ref: '#/components/schemas/AuthenticationModel'
          description: Set of fields that should be provided in the initial POST `authenticate` request.
        authenticationSteps:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AuthenticationModel'
          description: Set of fields that should be provided depending on the status of the response of the first POST `authenticate` request.
        mfaSchemes:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/MfaScheme'
          description: Supported MFA schemes, can be none or multiple.
        instructionsUrl:
          type:
          - string
          - 'null'
          description: Optional URL with the instructions explaining how to create a set of API key/secret for the integration, can be shown to the end user.
      additionalProperties: false
    AuthenticationModel:
      type: object
      properties:
        authResponse:
          allOf:
          - $ref: '#/components/schemas/B2BBrokerAuthResponse'
        fields:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AuthenticationFieldDescription'
          description: Set of fields that are expected to be provided based on the status of the AuthResponse
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    ApiResultStatus:
      enum:
      - ok
      - serverFailure
      - permissionDenied
      - badRequest
      - notFound
      - conflict
      - tooManyRequest
      - locked
      type: string
  securitySchemes:
    Client-Secret:
      type: apiKey
      description: Contact Mesh to get client Secret
      name: X-Client-Secret
      in: header
    Client-Id:
      type: apiKey
      description: Contact Mesh to get client Id
      name: X-Client-Id
      in: header