{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/snaptrade/main/json-schema/snaptrade-brokerage-authorization-schema.json",
  "title": "BrokerageAuthorization",
  "description": "A single connection with a brokerage. Note that `Connection` and `Brokerage Authorization` are interchangeable, but the term `Connection` is preferred and used in the doc for consistency.\n\nA connection is usually tied to a single login at a brokerage. A single connection can contain multiple brokerage accounts.\n\nSnapTrade performs de-duping on connections for a given user. If the user has an existing connection with the brokerage, when connecting the brokerage with the same credentials, SnapTrade will return the existing connection instead of creating a new one.\n",
  "x-generated": "2026-10-21",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/snaptrade-openapi.yml#/components/schemas/BrokerageAuthorization",
  "type": "object",
  "properties": {
    "id": {
      "$ref": "#/$defs/BrokerageAuthID"
    },
    "created_date": {
      "description": "Timestamp of when the connection was established in SnapTrade.",
      "type": "string",
      "format": "date-time"
    },
    "brokerage": {
      "$ref": "#/$defs/Brokerage"
    },
    "name": {
      "description": "A short, human-readable name for the connection.",
      "type": "string"
    },
    "type": {
      "description": "Whether the connection is read-only or trade-enabled. A read-only connection can only be used to fetch data, while a trade-enabled connection can be used to place trades. Valid values are `read` and `trade`.",
      "type": "string"
    },
    "disabled": {
      "description": "Whether the connection is disabled. A disabled connection can no longer access the latest data from the brokerage, but will continue to return the last cached state. A connection can become disabled for many reasons and differs by brokerage. Here are some common scenarios:\n\n- The user has changed their username or password at the brokerage.\n- The user has explicitly removed the access grant at the brokerage.\n- The session has expired at the brokerage and now requires explicit user re-authentication.\n\nPlease see [this guide](/docs/fix-broken-connections) on how to fix a disabled connection.\n",
      "type": "boolean"
    },
    "disabled_date": {
      "description": "Timestamp of when the connection was disabled in SnapTrade.",
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "meta": {
      "deprecated": true,
      "description": "Additional data about the connection. This information is specific to the brokerage and there's no standard format for this data. This field is deprecated and subject to removal in a future version.",
      "type": "object"
    },
    "updated_date": {
      "deprecated": true,
      "description": "Timestamp of when the connection was last updated in SnapTrade. This field is deprecated. Please let us know if you have a valid use case for this field.",
      "type": "string",
      "format": "date-time"
    },
    "is_eligible_for_payout": {
      "description": "Whether the connection is eligible for a payout. This is an experimental field that is NOT generally available for all partners. Do not use in production without speaking to the SnapTrade team.",
      "type": "boolean"
    },
    "data_freshness_mode": {
      "description": "Indicates the data freshness provided by the institution and by SnapTrade for this connection. The two values are independent; the connection's data is effectively delayed if either value is `delayed`.\n\nThe \"Data freshness\" column on the [SnapTrade Institution Support](https://support.snaptrade.com/brokerages) page (Positions & recent orders tab) identifies institutions whose connections are considered delayed on a Real-time plan because either `institution` or `snaptrade` is `delayed`.\n",
      "type": "object",
      "required": [
        "institution",
        "snaptrade"
      ],
      "properties": {
        "institution": {
          "description": "Indicates the freshness of the data provided by the institution. `realtime` means the institution provides current data; `delayed` means the institution itself does not allow intra-day data updates.\n",
          "type": "string",
          "enum": [
            "realtime",
            "delayed"
          ]
        },
        "snaptrade": {
          "description": "Indicates how SnapTrade retrieves data for this connection. `realtime` means SnapTrade retrieves current data from the institution during API calls. `delayed` means SnapTrade serves cached data, either because the customer's plan uses Daily data or because retrieving live data from the institution is too latency-intensive.\n\nWhen this value is `delayed`, you can request updated data using the [manual refresh endpoint](/reference/Connections/Connections_refreshBrokerageAuthorization).\n",
          "type": "string",
          "enum": [
            "realtime",
            "delayed"
          ]
        }
      },
      "additionalProperties": false
    }
  },
  "$defs": {
    "Brokerage": {
      "description": "Describes a brokerage that SnapTrade supports.",
      "type": "object",
      "properties": {
        "id": {
          "description": "Unique identifier for the brokerage firm. This is the UUID used to reference the brokerage in SnapTrade.",
          "type": "string",
          "format": "uuid"
        },
        "slug": {
          "description": "A short, unique identifier for the brokerage. It is usually the name of the brokerage in capital letters and will never change.",
          "type": "string"
        },
        "name": {
          "description": "Full name of the brokerage.",
          "type": "string"
        },
        "display_name": {
          "description": "A display-friendly name of the brokerage.",
          "type": "string"
        },
        "description": {
          "description": "A brief description of the brokerage.",
          "type": "string"
        },
        "aws_s3_logo_url": {
          "description": "URL to the brokerage's logo.",
          "type": "string",
          "format": "url"
        },
        "aws_s3_square_logo_url": {
          "description": "URL to the brokerage's logo in square format.",
          "type": [
            "string",
            "null"
          ],
          "format": "url"
        },
        "url": {
          "description": "URL to the brokerage's website. Returns null if the brokerage has no website on record.",
          "type": [
            "string",
            "null"
          ],
          "format": "url"
        },
        "enabled": {
          "description": "Whether the brokerage is enabled in SnapTrade. A disabled brokerage will not be available for new connections.",
          "type": "boolean"
        },
        "maintenance_mode": {
          "description": "Whether the brokerage is currently in maintenance mode. A brokerage in maintenance mode will not be available for new connections.",
          "type": "boolean"
        },
        "is_degraded": {
          "description": "Whether the brokerage is currently degraded. A degraded brokerage may have reduced functionality or be experiencing technical issues.",
          "type": "boolean"
        },
        "allows_trading": {
          "description": "Whether the brokerage allows trading through SnapTrade.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "allows_fractional_units": {
          "deprecated": true,
          "description": "This field is deprecated. Please contact us if you have a valid use case for it.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "has_reporting": {
          "deprecated": true,
          "description": "This field is deprecated. Please contact us if you have a valid use case for it.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "is_real_time_connection": {
          "deprecated": true,
          "description": "This field is deprecated. Please contact us if you have a valid use case for it.",
          "type": "boolean"
        },
        "brokerage_type": {
          "$ref": "#/$defs/BrokerageType"
        },
        "exchanges": {
          "deprecated": true,
          "description": "This field is deprecated. Please contact us if you have a valid use case for it.",
          "type": "array",
          "items": {}
        },
        "open_url": {
          "deprecated": true,
          "description": "This field is deprecated.",
          "type": [
            "string",
            "null"
          ],
          "format": "url"
        }
      }
    },
    "BrokerageAuthID": {
      "description": "Unique identifier for the connection (brokerage_authorization_id). This is the UUID used to reference the connection in SnapTrade.",
      "type": "string",
      "format": "uuid"
    },
    "BrokerageType": {
      "description": "Type of brokerage. Currently supports traditional brokerages and crypto exchanges.",
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/$defs/Id"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Id": {
      "type": "string",
      "format": "uuid"
    }
  }
}