Asset Classes

Free investment financial education


Multilingual content from IBKR

Close Navigation
Learn more about IBKR accounts
Tutorial: Web API – Connect to Brokerage Session

Tutorial: Web API – Connect to Brokerage Session

Posted May 10, 2021 at 3:05 pm
Interactive Brokers

What is the Brokerage Session?

When authenticating your login session this allows you equivalent access as a read-only user. You can query positions, account details, security definition and portfolio analyst data. Once authenticated, you can then connect to the brokerage session which provides access to market data, scanners and placing orders. There are two different brokerage sessions offered. We provide brokerage session that allows access to all the /iserver endpoints, the same way Client Portal and IBKR Mobile authenticates. We provide brokerage session directly to CCP (currently in Beta). This allows access to all the /ccp endpoints, the same way Trader Workstation authenticates. Interactive Brokers only allows access to one brokerage session at a time. In this topic we’ll describe further how to connect to the /iserver endpoints. When using the Web API we use an OAuth protected-resource POST request to connect to the brokerage session.

Please be sure to authenticate first in order to resolve the below URLs.
For authentication details, visit

SSODH Init Request


The body, of type x-www-form-urlencoded, must have the following parameters:

  •           machineId (String)       8 char alphanumberic string e.g. CCCCCC01-99
  •           mac (String)                   six 2-char alphanumerical pairs separated by a hyphen
  •           compete (Boolean)      whether or not the session should compete, usually set to false
  •           locale (String)                set to “en_US
  •           username (String)        set to dash “-“

If the request is successful, the response will contain a challenge in hex format.


Request Payload

Response Payload
challenge “c0af5b21fec49f5e08fc7fd82fbe11b7422f499b”

Challenge and Response

The challenge is needed to calculate the challenge response, or R whereby seed = challenge, verifier = st.

To calculate R, ensure both the challenge and session token calculated during initial authentication are in hex form. Then, concatenate the challenge and session tokens, with the challenge being in front.

Method for calculating R:

export function compute_sk(seed, verifier) {
     const hash = crypto.createHash(‘sha1’);
     hash.update(Buffer.from(seed + verifier, ‘hex’));
     return hash.digest(‘hex’);

SSODH Response Request


The body only has one parameter, “response”, with the value being the response calculated for R above.

If the request is successful, the response will contain a JSON object with the values “passed”, “authenticated” and “connected” being true.


Request Payload

Response Payload

How do I connect to Brokerage Session when using the Gateway?

When running the headless gateway you would manually login via URL. Then send the endpoint:

GET  https://localhost:5000/v1/api/iserver/accounts 

The gateway will automatically send the SSODH Init and SSODH Response for you. If you receive account information back this confirms you are connected.

At any time you can check the status of the brokerage session by sending the endpoint:

GET  https://localhost:5000/v1/api/iserver/auth/status

If authentication returns false you can try to reauthenticate by sending the endpoints:

GET  https://localhost:5000/v1/api/sso/validate and POST  https://localhost:5000/v1/api/iserver/reauthenticate

If you have any further questions or issues connecting to the brokerage session please reach-out to the API Group at

Visit the IBKR API Center for Downloads, Resources, and Technical Details:

Disclosure: Interactive Brokers

The analysis in this material is provided for information only and is not and should not be construed as an offer to sell or the solicitation of an offer to buy any security. To the extent that this material discusses general market activity, industry or sector trends or other broad-based economic or political conditions, it should not be construed as research or investment advice. To the extent that it includes references to specific securities, commodities, currencies, or other instruments, those references do not constitute a recommendation by IBKR to buy, sell or hold such investments. This material does not and is not intended to take into account the particular financial conditions, investment objectives or requirements of individual customers. Before acting on this material, you should consider whether it is suitable for your particular circumstances and, as necessary, seek professional advice.

The views and opinions expressed herein are those of the author and do not necessarily reflect the views of Interactive Brokers, its affiliates, or its employees.

IBKR Campus Newsletters

This website uses cookies to collect usage information in order to offer a better browsing experience. By browsing this site or by clicking on the "ACCEPT COOKIES" button you accept our Cookie Policy.