OAuth 2.0

Initialize Brokerage Session

View as MarkdownOpen in Claude

This guide documentshow to make authenticated requests to IBKR’s Client Portal API once a Bearer session token has been established. Unlike the preceding OAuth2 steps, this is not a token-issuance exchange; it is the pattern used for all subsequent authenticated API calls. It is demonstrated here against the /iserver/auth/ssodh/init endpoint, which activates (initializes) the brokerage session required before trading or account-data endpoints become usable.

This is the final step in the IBKR OAuth2 authentication flow, following:

  1. Access Token
  2. Bearer Token / SSO Session
  3. Initialize Brokerage Session (authenticated request, documented here)
1

Prerequisites

Before implementing this flow, ensure you have:

RequirementDescription
Bearer TokenThe session token (bearerToken) obtained from the Bearer Token / SSO Session step; presented as a standard Bearer credential
Client Portal Base URLIBKR’s Client Portal API host (clientPortalUrl)
2

Construct the Endpoint URL

Authenticated Client Portal endpoints are accessed over HTTPS, using whichever HTTP method the target endpoint requires. /iserver/auth/ssodh/init specifically requires POST.

1request_url = "https://api.ibkr.com/v1/api/iserver/auth/ssodh/init"
3

Assemble Standard Headers

1req_headers = {
2    "Host": "api.ibkr.com",
3    "User-Agent": "python/3.x",
4    "Accept": "*/*",
5    "Connection": "keep-alive",
6    "Authorization": f"Bearer {bearer_token}",
7    "Content-Type": "application/json"
8}
HeaderPurpose
HostExplicitly pinned to api.ibkr.com; redundant with the URL’s host but set defensively, since it is also applied as a session-level default
User-AgentIdentifies the calling client; update this to your actual runtime/environment rather than hardcoding a placeholder value, consistent with IBKR’s integration guidelines
AcceptSet to */*, accepting any response content type IBKR returns
ConnectionSet to keep-alive to reuse the underlying TCP connection across sequential authenticated calls, in conjunction with the persistent session object
AuthorizationSet to Bearer <bearer_token> — the SSO session token obtained from the Bearer Token step, not the OAuth2 access token from the earlier step
4

Construct the Request Body

1req_content = {"compete": True, "publish": True}
FieldPurpose
competeWhen true, instructs IBKR to take over (compete for) the brokerage session even if another session is already active for the account, rather than failing the initialization
publishWhen true, instructs IBKR to publish session status updates, which downstream consumers (e.g. a streaming websocket connection) can subscribe to. This must be set to true
5

Execute the Request

1endpoint = "/iserver/auth/ssodh/init"
2req_content = {"compete": True, "publish": True}
3
4requests.post(url=endpoint, headers=req_headers, json=req_content)