ibauth 0.0.8

Interactive Brokers OAuth

IBKR Authentication Workflow

Interactive Brokers provides an extensive API that can be used for trading and account management.

It's also possible to authenticate for the API via OAuth.

ibauth is a Python client for handling the full Interactive Brokers (IBKR) Web API authentication flow. It wraps the OAuth2 + session lifecycle steps (access_token, bearer_token, ssodh_init, tickle, etc.) into a simple, reusable interface.

🔑 Features:

• Obtain and refresh IBKR OAuth2 tokens.
• Manage brokerage sessions (ssodh_init, validate_sso, tickle, logout).
• YAML-based configuration (easy to keep credentials outside of code).
• Logging of requests and responses for troubleshooting.

Documentation for the IBKR Web API can be found in the official reference.

API Gateway

https://www.interactivebrokers.com/campus/ibkr-api-page/cpapi-v1/#gw-step-one

Basically during the process the java app creates a local address to which you use as the base URL. The java app then handles all the encrypted stuff between it and IBKR. Once the portal is setup, then you need to go to it, and there will be a loing page, you need to input your details and submit, I used Python believe it or not, with Selenium. At that stage the warning bells should have rung that Matlab could not do this, hence having to do Python. And no ChatGPT back then, it was shit hard figure it out. Dunno how I did it, must have been all thos monkeys typing random stuff on those keyboards. Anyhow, then when you submite, they requre authentication. Forpaper trading account you could use and SMS code, and this could be achieved through google messages, no hardware needed. BUT, when it came to live acounts, that is 2FA, straight through their app and it pops up asking you to click, then to ask if you want to proceed, then provide your fingerprint. That is where the robot came in.

When OAuth is selected as an authentication method with IBKR, this is typically allocated to a FA (Financial Advisor) account, which may have 1 or more client accounts under its control. Typically the FA account will have have paid data subscriptions which provide real-time market data, and this may be applied in the trading functions on all the client accounts. The FA account directs trading on behalf of the client accounts, with their allocated capital.

---

Requirements

• Python 3.11+
• A valid IBKR account with Web API access enabled.
• An RSA private key (.pem) registered with IBKR.

Dependencies are listed in requirements.txt.

---

Installation

You can install either from PyPI (preferred) or GitHub (which may give access to updates not yet published on PyPI).

# Install from PyPI.
pip install ibauth

# Install from GitHub.
pip install git+https://github.com/datawookie/ibkr-oauth-flow

---

Configuration

Authentication parameters are supplied via a YAML configuration file:

client_id: "your-client-id"
client_key_id: "your-client-key-id"
credential: "your-credential"
private_key_file: "/path/to/privatekey.pem"
domain: "api.ibkr.com"

• client_id: Application client ID from IBKR.
• client_key_id: Key identifier associated with your private key.
• credential: IBKR credential string.
• private_key_file: Path to your RSA private key (.pem).
• domain: Usually api.ibkr.com, but IBKR supports numbered subdomains (1.api.ibkr.com, 5.api.ibkr.com, …).

---

How It Works

The IBKR Web API requires multiple steps to establish and maintain a brokerage session. ibauth automates these steps:

1. Access Token Exchange your client credentials + JWS for an access token. → auth.get_access_token()

2. Bearer Token Use the access token and your public IP to obtain a bearer token. → auth.get_bearer_token()

3. Session Initialisation Start a brokerage session using the bearer token. → auth.ssodh_init()

4. Session Validation (optional) Confirm that your session is active. → auth.validate_sso()

5. Keepalive ("Tickle") Periodically ping the API to keep the session alive. → auth.tickle()

6. Logout End the session when finished. → auth.logout()

    +--------------+        +--------------+        +---------------+
    |  Access      |        |  Bearer      |        |  Brokerage    |
    |  Token       | -----> |  Token       | -----> |  Session      |
    +--------------+        +--------------+        +---------------+
           |                        |                        |
           v                        v                        v
    get_access_token()     get_bearer_token()       ssodh_init() / tickle()

---

Quick Start

import logging
import time
import ibauth

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)7s] %(message)s",
)

logging.getLogger("urllib3").setLevel(logging.WARNING)
logging.getLogger("charset_normalizer").setLevel(logging.WARNING)

if __name__ == "__main__":
    auth = ibauth.auth_from_yaml("config.yaml")

    auth.get_access_token()
    auth.get_bearer_token()

    auth.ssodh_init()
    auth.validate_sso()

    # Keep session alive
    for _ in range(3):
        auth.tickle()
        time.sleep(10)

    # Dynamically change the API domain
    auth.domain = "5.api.ibkr.com"
    auth.tickle()

    auth.logout()

Testing

This project uses pytest. To run the test suite:

pytest

To include coverage:

pytest --cov=src/ibauth --cov-report=term-missing

Development

Clone the repo and install dependencies into a virtual environment:

git clone https://github.com/datawookie/ibkr-oauth-flow.git
cd ibkr-oauth-flow
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Deploy to PyPI

This requires UV_PUBLISH_TOKEN to be set to a PyPi token in environment.

Publishing requires a PyPI token (UV_PUBLISH_TOKEN) to be available in your environment.

make deploy