Tutorial: Web API – Connect to Brokerage Session

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 https://www.interactivebrokers.com/en/trading/ib-api.php.

SSODH Init Request

POST  https://api.ibkr.com/v1/api/iserver/auth/ssodh/init

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.

Example:

Request Payload
compete=true&locale=en_US&mac=48-DF-37-57-33-80&machineId=CCCCCC62&username=-

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

POST  https://api.ibkr.com/v1/api/iserver/auth/ssodh/response

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.

Example:

Request Payload
response=cff337ae870bba404d58d41836e6a8cf7e1a5e86

Response Payload
{“passed”:true,”authenticated”:true,”connected”:true,”competing”:false}

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 https://www.interactivebrokers.com/en/index.php?f=47047.

Visit the IBKR API Center for Downloads, Resources, and Technical Details:
https://www.interactivebrokers.com/en/trading/ib-api.php.