SnapTrade Authentication API

openapi: 3.2.0
info:
  description: 'Connect brokerage accounts to your app for live positions and trading.


    ## Rate limiting


    Two limits apply to requests signed with your `clientId`. The stricter one

    wins, and exceeding either returns `429 Too Many Requests`.


    - **Customer-level** — 250 requests/minute by default, scoped to your

    `clientId` and applied across all endpoints. Reported in

    `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.

    - **Account-level** — 10 requests/minute per account, scoped to

    (`clientId`, `accountId`). All covered operations for one account draw on

    the same bucket — reading balances and reading positions share it — and

    enforcement does not depend on the HTTP method, so updating an account

    consumes the same bucket as reading it. Only enforced for Personal users,

    and only for integrations it has been rolled out to — it is not yet in

    force for every Personal integration. It also does not apply on every

    operation that documents a 429 below. Where it applies it is reported in

    `X-RateLimit-Account-Limit`, `X-RateLimit-Account-Remaining` and

    `X-RateLimit-Account-Reset`. Do not read the absence of those headers as

    proof the limit is off — some configurations omit the rate limit headers

    while still enforcing the limit, so header absence tells you nothing

    about your allowance.


    On a 429, `X-RateLimit-Remaining: 0` means you hit the customer-level limit

    and `X-RateLimit-Account-Remaining: 0` means the account-level one. Wait for

    the corresponding `*-Reset` value (seconds) before retrying, or fall back to

    exponential backoff with jitter.


    Not every 429 is explained by those headers. A separate

    per-authenticated-user limit, reported in no `X-RateLimit-*` header, covers

    OAuth-authenticated requests and signed requests in configurations where the

    customer-level limit is not in effect — on the operations that use the

    default throttles. A few operations override those and are governed by the

    customer-level limit alone. The two do not stack: a signed request

    governed by the customer-level limit above is not additionally subject to the

    per-user one. If a 429 arrives with no header at zero — or with no

    `X-RateLimit-*` headers at all — honour `Retry-After` and back off. Treat the

    remaining counts as a hint, not a guarantee that the next request will

    succeed.


    Because the customer-level limit applies everywhere, any signed request can

    return 429.


    **OAuth-authenticated requests are an exception.** They are not subject to

    the customer-level limit and do not receive `X-RateLimit-Limit`,

    `X-RateLimit-Remaining` or `X-RateLimit-Reset` — do not wait on those headers

    or design around a customer-level allowance on this path. The account-level

    limit still applies to them on the account-data endpoints above, reported in

    the `X-RateLimit-Account-*` headers. On operations using the default

    throttles the per-user limit above applies to them as well, so an OAuth

    request can be rejected while the account headers still show capacity; on

    the few operations that override those throttles, OAuth callers have no

    per-user ceiling at all. Drive retries from `Retry-After` and exponential

    backoff with jitter rather than from the headers.


    See https://docs.snaptrade.com/docs/ratelimiting.'
  version: 1.0.0
  title: SnapTrade Authentication API
  termsOfService: N/A
  contact:
    email: api@snaptrade.com
  x-konfig-ignore:
    potential-incorrect-type: true
  x-readme:
    explorer-enabled: false
servers:
- description: SnapTrade Production API
  url: https://api.snaptrade.com
security:
- PartnerSignature: []
  PartnerClientId: []
  PartnerTimestamp: []
tags:
- name: Authentication
  description: Register and authenticate users with SnapTrade.
paths:
  /snapTrade/listUsers:
    get:
      tags:
      - Authentication
      summary: List all users
      operationId: Authentication_listSnapTradeUsers
      description: Returns a list of all registered user IDs. Please note that the response is not currently paginated.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400FailedRequestResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404FailedRequestResponse'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500UnexpectedExceptionResponse'
  /snapTrade/registerUser:
    post:
      tags:
      - Authentication
      summary: Register user
      description: 'Registers a new SnapTrade user under your Client ID. A user secret will be automatically generated for you and must be properly stored in your system.

        Most SnapTrade operations require a user ID and user secret to be passed in as parameters.'
      operationId: Authentication_registerSnapTradeUser
      requestBody:
        $ref: '#/components/requestBodies/RegisterUserRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserIDandSecret'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400FailedRequestResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404FailedRequestResponse'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500UnexpectedExceptionResponse'
  /snapTrade/deleteUser:
    delete:
      tags:
      - Authentication
      summary: Delete user
      operationId: Authentication_deleteSnapTradeUser
      description: Deletes a registered user and all associated data. This action is irreversible. This API is asynchronous and will return a 200 status code if the request is accepted. The user and all associated data will be queued for deletion. Once deleted, a `USER_DELETED` webhook will be sent.
      parameters:
      - in: query
        required: true
        name: userId
        schema:
          $ref: '#/components/schemas/UserID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteUserResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400FailedRequestResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403FailedRequestResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404FailedRequestResponse'
        '500':
          description: Unexpected Error
  /snapTrade/login:
    post:
      tags:
      - Authentication
      summary: Generate Connection Portal URL
      operationId: Authentication_loginSnapTradeUser
      description: 'Authenticates a SnapTrade user and returns the Connection Portal URL used for connecting brokerage accounts. Please check this guide for how to integrate the Connection Portal into your app.


        Please note that the returned URL expires in 5 minutes.'
      parameters:
      - in: query
        required: true
        name: userId
        schema:
          $ref: '#/components/schemas/UserID'
      - in: query
        required: true
        name: userSecret
        schema:
          $ref: '#/components/schemas/UserSecret'
      requestBody:
        $ref: '#/components/requestBodies/SnapTradeLoginUserRequestBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/LoginRedirectURI'
                - $ref: '#/components/schemas/encryptedResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400FailedRequestResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403FailedRequestResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404FailedRequestResponse'
        '500':
          description: Unexpected Error
  /snapTrade/resetUserSecret:
    post:
      tags:
      - Authentication
      summary: Rotate user secret
      description: Rotates the secret for a SnapTrade user. You might use this if `userSecret` is compromised. Please note that if you call this endpoint and fail to save the new secret, you'll no longer be able to access any data for this user, and your only option will be to delete and recreate the user, then ask them to reconnect.
      operationId: Authentication_resetSnapTradeUserSecret
      requestBody:
        $ref: '#/components/requestBodies/ResetUserSecretRequestBody'
      responses:
        '200':
          description: New user secret is generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserIDandSecret'
        '400':
          description: Bad Request. Could be caused by various reasons. Error message is provided in response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400FailedRequestResponse'
        '401':
          description: Failed authentication. Wrong clientId, userId or userSecret provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401FailedRequestResponse'
        '403':
          description: Forbidden. The user's secret is managed by a first-party app and cannot be reset here
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403FailedRequestResponse'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500UnexpectedExceptionResponse'
components:
  requestBodies:
    RegisterUserRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SnapTradeRegisterUserRequestBody'
    SnapTradeLoginUserRequestBody:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SnapTradeLoginUserRequestBody'
    ResetUserSecretRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserIDandSecret'
  schemas:
    UserList:
      description: List of registered SnapTrade user IDs
      type: array
      items:
        $ref: '#/components/schemas/UserID'
      example:
      - user1
      - user2
      - user3
    404FailedRequestResponse:
      description: Example for failed request response
      type: object
      properties:
        default_detail:
          example: The requested resource does not exist.
        default_code:
          example: 1011
    LoginRedirectURI:
      description: Redirect uri upon successful login
      type: object
      properties:
        redirectURI:
          description: Connection Portal link to redirect user to connect a brokerage account.
          type: string
          example: https://app.snaptrade.com/snapTrade/redeemToken?token=npVKchZrL0MYIHTusGfADT74r4xXpHkmbxbQDmt0RINLXbQ5cWsvGkPSgMQRxz8/cnxjzL9T2NWLuHuDyidHiCNeXXTb/tVhzC2olSyfxWW6DRrkUppArGCdmkIHyBMzog6C55P8yoqzcGer5Hml0Q%3D%3D&clientId=WEALTHLY&broker=ROBINHOOD&connectionPortalVersion=v4&sessionId=cf371bb4-a475-4f17-ab94-d0fee699960d
        sessionId:
          description: ID to identify the connection portal session.
          type: string
          example: cf371bb4-a475-4f17-ab94-d0fee699960d
    SnapTradeLoginUserRequestBody:
      description: Data to login a user via SnapTrade Partner
      type: object
      properties:
        broker:
          description: Slug of the brokerage to connect the user to. See [the integrations page](https://support.snaptrade.com/brokerages) for a list of supported brokerages and their slugs.
          type: string
          example: ALPACA
        immediateRedirect:
          description: When set to `true`, user will be redirected back to the partner's site instead of the connection portal. This parameter is ignored if the connection portal is loaded inside an iframe. See the [guide on ways to integrate the connection portal](/docs/implement-connection-portal) for more information.
          type: boolean
          example: true
        customRedirect:
          description: URL to redirect the user to after the user connects their brokerage account. This parameter is ignored if the connection portal is loaded inside an iframe. See the [guide on ways to integrate the connection portal](/docs/implement-connection-portal) for more information.
          type: string
          example: https://snaptrade.com
        reconnect:
          description: The UUID of the brokerage connection to be reconnected. This parameter should be left empty unless you are reconnecting a disabled connection. See the [guide on fixing broken connections](/docs/fix-broken-connections) for more information.
          type: string
          example: 8b5f262d-4bb9-365d-888a-202bd3b15fa1
        connectionType:
          description: 'Determines connection permissions (default: read) - `read`: Data access only. - `trade`: Data and trading access. - `trade-if-available`: Attempts to establish a trading connection if the brokerage supports it, otherwise falls back to read-only access automatically.

            '
          type: string
          enum:
          - read
          - trade
          - trade-if-available
          default: read
        showCloseButton:
          description: Controls whether the close (X) button is displayed in the connection portal. When false, you control closing behavior from your app. Defaults to true.
          type: boolean
          example: true
        darkMode:
          description: Enable dark mode for the connection portal. Defaults to false.
          type: boolean
          example: true
        locale:
          description: 'Language the connection portal renders in. `en` and `pt-BR` are the languages we ship; any other language is rejected with a 400. Matching is case- and separator-insensitive, so `pt-br`, `pt-BR` and `pt_BR` are equivalent, and a regional tag resolves to the language when we ship it, so `en-US` renders `en`. Deliberately not an enum: those equivalent spellings are all accepted by the API, and an enum would have generated SDKs reject them before the request is sent. Screens without translated copy fall back to English individually. Defaults to `en`.

            '
          type: string
          example: pt-BR
          default: en
        connectionPortalVersion:
          description: Sets the connection portal version to render. Currently only `v4` is supported and is the default. All other versions are deprecated and will automatically be set to v4.
          type: string
          example: v4
          enum:
          - v4
          - v3
          - v2
          default: v4
    DeleteUserResponse:
      type: object
      properties:
        status:
          description: This is always `deleted` when a user is queued for deletion.
          type: string
          example: deleted
        detail:
          description: Human friendly message about the deletion status.
          type: string
          example: User queued for deletion; please wait for webhook for confirmation.
        userId:
          $ref: '#/components/schemas/UserID'
    400FailedRequestResponse:
      description: Example for failed request response
      type: object
      properties:
        default_detail:
          example: Unable to verify data sent
        default_code:
          example: 1076
    UserIDandSecret:
      type: object
      properties:
        userId:
          $ref: '#/components/schemas/UserID'
        userSecret:
          $ref: '#/components/schemas/UserSecret'
    encryptedResponse:
      description: "This response consists of 2 different components that must be decrypted to obtain the decrypted message\n\n* Decrypting the encryptedSharedKey\n\n  The encrypted shared key is a shared key that was randomly generated by SnapTrade and encrypted using the users SSH public key provided when registering the user\n  It is needed to decrypt the message in step 2.\n\n  To decrypt the shared key, the user should have access to their SSH private key stored locally in their device\n\n  An example Python code on how to decrypt the shared key is shown below\n\n  ```\n  def decrypt_rsa_message(self, encrypted_message):\n      from Crypto.Cipher import PKCS1_OAEP\n      from Crypto.PublicKey import RSA\n      from base64 import b64decode\n\n      f = open('private.pem', 'r')\n      private_key = RSA.import_key(f.read())\n      cipher = PKCS1_OAEP.new(private_key)\n\n      return cipher.decrypt(b64decode(encrypted_message.encode())).decode()\n  ```\n\n* Decrypting the encryptedMessageData\n\n   The data meant to be returned by an endpoint can be obtained by decrypting the encrypted message\n\n   An encrypted message is a message that is encrypted using AES - MODE OCB with the shared key obtained in step one\n\n  An example code to decrypt the encrypted message is shown below\n\n  ```\n  def decrypt_aes_message(self, shared_key, encrypted_message):\n      from Crypto.Cipher import AES\n      from base64 import b64decode\n\n      encrypted_msg = b64decode(encrypted_message[\"encryptedMessage\"].encode())\n      tag = b64decode(encrypted_message[\"tag\"].encode())\n      nonce = b64decode(encrypted_message[\"nonce\"].encode())\n      cipher = AES.new(shared_key.encode(), AES.MODE_OCB, nonce=nonce)\n\n      return cipher.decrypt_and_verify(encrypted_msg, tag).decode()\n  ```\n"
      type: object
      additionalProperties: false
      properties:
        encryptedSharedKey:
          type: string
          example: 5UEaY9QGzcNTr8y2jGDUI79jY1OdfK9x
        encryptedMessageData:
          type: object
          properties:
            encryptedMessage:
              type: string
              example: 9Xy05vqZOfp0OpW5fLAaDw==
            tag:
              type: string
              example: mWZPkpQh5ktbcz6N7cTRmQ==
            nonce:
              type: string
              example: None
    UserSecret:
      description: SnapTrade User Secret. This is a randomly generated string and should be stored securely. If compromised, please rotate it via the [rotate user secret endpoint](/reference/Authentication/Authentication_resetSnapTradeUserSecret).
      type: string
      example: adf2aa34-8219-40f7-a6b3-60156985cc61
    SnapTradeRegisterUserRequestBody:
      description: Data required to register a user via SnapTrade Partner
      type: object
      required:
      - userId
      properties:
        userId:
          $ref: '#/components/schemas/UserID'
    403FailedRequestResponse:
      description: Example for failed request response
      type: object
      properties:
        default_detail:
          example: User does not have permission to access this resource
        default_code:
          example: 1066
    401FailedRequestResponse:
      description: Example for failed request response
      type: object
      properties:
        default_detail:
          example: Unable to verify signature sent
        default_code:
          example: 1076
    500UnexpectedExceptionResponse:
      description: Example for a response that failed for unexpected reasons
      type: object
      properties:
        detail:
          example: Encountered an unexpected exception.
        status_code:
          example: 500
        code:
          example: 1000
    UserID:
      description: SnapTrade User ID. This is chosen by the API partner and can be any string that is a) unique to the user, and b) immutable for the user. It is recommended to NOT use email addresses for this property because they are usually not immutable.
      type: string
      example: snaptrade-user-123
  securitySchemes:
    PartnerSignature:
      type: apiKey
      in: header
      name: Signature
    PartnerClientId:
      type: apiKey
      in: query
      name: clientId
    PartnerTimestamp:
      type: apiKey
      in: query
      name: timestamp