IBKR Session Management

Maintain active sessions with Interactive Brokers to keep your API connection alive and functional. IBKR sessions require periodic validation and refresh to prevent timeout.

Overview

IBKR API sessions have timeouts and require active maintenance. This guide covers the endpoints needed to validate, refresh, and manage your session state.

Key Endpoints

1. Initialize Session

Initialize a new session with Interactive Brokers.

IBKR Documentation

Endpoint:

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

Purpose: Start a new session to establish connection and receive session tokens

Request:

{
  "publish": true,
  "compete": true
}

Response:

{
  "success": {
    "value": {
      "authenticated": true,
      "established": true,
      "competing": false,
      "connected": true,
      "message": "",
      "MAC": "98:F2:B3:23:BF:A0",
      "serverInfo": {
        "serverName": "JifN19053",
        "serverVersion": "Build 10.25.0p, Dec 5, 2023 5:48:12 PM"
      }
    }
  }
}

2. Validate Session

Check if your current session is valid.

IBKR Documentation

Endpoint:

GET https://api.ibkr.com/v1/api/sso/validate

Purpose: Confirm session validity before executing trades

Response:

{
  "success": {
    "value": {
      "USER_ID": 123456789,
      "USER_NAME": "user1234",
      "RESULT": true,
      "AUTH_TIME": 1702580846836,
      "SF_ENABLED": false,
      "IS_FREE_TRIAL": false,
      "CREDENTIAL": "user1234",
      "IP": "12.345.678.901",
      "EXPIRES": 415890,
      "QUALIFIED_FOR_MOBILE_AUTH": null,
      "LANDING_APP": "UNIVERSAL",
      "IS_MASTER": false,
      "lastAccessed": 1702581069652,
      "LOGIN_TYPE": 2,
      "PAPER_USER_NAME": "user1234",
      "features": {
        "env": "PROD",
        "wlms": true,
        "realtime": true,
        "bond": true,
        "optionChains": true,
        "calendar": true,
        "newMf": true
      },
      "region": "NJ"
    }
  }
}

Status Codes:

200 - Session is valid
401 - Session expired or invalid

3. Authentication Status

Get detailed authentication and connection status.

IBKR Documentation

Endpoint:

GET https://api.ibkr.com/v1/api/iserver/auth/status

Purpose: Check if you're authenticated, connected, and competitive (no other sessions)

Response:

{
  "MAC": "12:B:B3:23:BF:A0",
  "authenticated": true,
  "established": true,
  "competing": false,
  "connected": true,
  "hardware_info": "21026956|06:8E:04:45:DA:8F",
  "message": "",
  "serverInfo": {
    "serverName": "JifN19053",
    "serverVersion": "Build 10.25.0p, Dec 5, 2023 5:48:12 PM"
  },
  "fail": ""
}

Response Fields:

Field	Meaning
`authenticated`	User is authenticated
`connected`	API connection established
`competing`	Another session exists (conflicts)

4. Tickle (Keep-Alive)

Send a keep-alive signal to maintain session.

IBKR Documentation

Endpoint:

GET https://api.ibkr.com/v1/api/tickle

Purpose: Refresh session timeout timer. Must be called regularly to keep the session alive.

Response:

{
  "session": "abc123xyz"
}

Keep-Alive Interval: Call every 60 seconds to maintain an active session. If no tickle is received for an extended period, the session will timeout.

5. Suppress Messages

Suppress IBKR confirmation dialogs for specific order types.

IBKR Documentation

Endpoint:

POST https://api.ibkr.com/v1/api/iserver/questions/suppress

Purpose: Avoid confirmation prompts for programmatic trading

Request:

{
  "messageIds": [
    "o163",
    "o354",
    "o382",
    "o383",
    "o403",
    "o451",
    "o2136",
    "o2137",
    "o2165",
    "o10082",
    "o10138",
    "o10151",
    "o10152",
    "o10153",
    "o10164",
    "o10223",
    "o10288",
    "o10331",
    "o10332",
    "o10333",
    "o10334",
    "o10335",
    "o10336",
    "p6",
    "p12"
  ]
}

Response:

{
  "status": "submitted"
}

Common Message IDs:

ID	Description
`o163`	Order confirmation dialogs
`o354`	Risk management warnings
`o382`	Commission warnings
`p6`	General confirmations

Session Maintenance Flow

1. Get Bearer Token
   └─> /brokerage-bearer-token

2. Initialize Session
   └─> POST /v1/api/iserver/auth/ssodh/init

3. Verify Connected
   └─> GET /v1/api/iserver/auth/status

4. Suppress Messages
   └─> POST /v1/api/iserver/questions/suppress

5. Keep Alive (every 60 seconds)
   └─> GET /v1/api/tickle

6. Before Trading
   └─> GET /v1/api/sso/validate
   └─> GET /v1/api/iserver/auth/status

7. Place Orders / Check Status
   └─> POST /v1/api/iserver/account/{acctId}/orders/whatif
   └─> POST /v1/api/iserver/account/{acctId}/orders
   └─> GET /v1/api/iserver/account/order/status/{orderId}

Implementation Example

const IBKR_BASE_PATH = "https://api.ibkr.com";

class SessionManager {
  constructor(bearerToken) {
    this.bearerToken = bearerToken;
    this.sessionId = null;
    this.keepAliveInterval = null;
  }

  async initializeSession() {
    const response = await fetch(
      `${IBKR_BASE_PATH}/v1/api/iserver/auth/ssodh/init`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${this.bearerToken}`,
          "Content-Type": "application/json",
          "User-Agent": "Your Application/1.0",
        },
        body: JSON.stringify({
          publish: true,
          compete: true,
        }),
      },
    );

    const data = await response.json();
    this.sessionId = data.sessionId;
    return data;
  }

  async validateSession() {
    const response = await fetch(`${IBKR_BASE_PATH}/v1/api/sso/validate`, {
      headers: {
        Authorization: `Bearer ${this.bearerToken}`,
        "User-Agent": "Your Application/1.0",
      },
    });

    return response.status === 200;
  }

  async getAuthStatus() {
    const response = await fetch(
      `${IBKR_BASE_PATH}/v1/api/iserver/auth/status`,
      {
        headers: {
          Authorization: `Bearer ${this.bearerToken}`,
          "User-Agent": "Your Application/1.0",
        },
      },
    );

    return response.json();
  }

  async suppressMessages() {
    await fetch(`${IBKR_BASE_PATH}/v1/api/iserver/questions/suppress`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${this.bearerToken}`,
        "Content-Type": "application/json",
        "User-Agent": "Your Application/1.0",
      },
      body: JSON.stringify({
        messageIds: ["o163", "o354", "o382", "o383", "o403", "o451"],
      }),
    });
  }

  async tickleSession() {
    await fetch(`${IBKR_BASE_PATH}/v1/api/tickle`, {
      headers: {
        Authorization: `Bearer ${this.bearerToken}`,
        "User-Agent": "Your Application/1.0",
      },
    });
  }

  startKeepAlive() {
    this.keepAliveInterval = setInterval(
      () => this.tickleSession(),
      60 * 1000, // Every 60 seconds
    );
  }

  stopKeepAlive() {
    if (this.keepAliveInterval) {
      clearInterval(this.keepAliveInterval);
    }
  }
}

Best Practices

Validate Before Trading - Always check validateSession() before placing orders
Keep Alive - Call tickle every 60 seconds to prevent session timeout
Monitor Status - Regularly check getAuthStatus() for competing sessions
Suppress Early - Suppress messages during session initialization
Handle Errors - Implement retry logic for failed session calls
Session Cleanup - Stop keep-alive timer when done

Troubleshooting

Issue	Solution
Session expired	Request new bearer token and reinitialize
Competing session	Another login exists; stop other sessions
Validation fails	Tickle session and retry
Messages not suppressed	Ensure message IDs are correct

Next Steps

IBKR Trading APIs - Place orders with active session
Complete IBKR Flow Example - Full working example