IBKR Authenticator App — for unattended live auth

IBKR sessions die. They die multiple times during the trading day and at least once overnight when IBKR's servers roll connections. The gateway has to be able to bring the session back up by itself, which means it has to answer IBKR's two-factor challenge by itself — without a human tapping a phone at 3 AM. That's what IBKR's "Authenticator App" option is for, and it's mandatory on any live connection in this gateway.

Paper accounts cannot have 2FA enabled — this whole page only applies to live accounts. To set up a paper account first, see how paper accounts work.

What "Authenticator App" actually is

IBKR's name for standard TOTP (RFC 6238). The same protocol Google Authenticator, Authy, 1Password, Yubico Authenticator and others implement. When you enroll, IBKR shows you:

a QR code for scanning into a phone app, and
an Activation Code — the same secret in human-readable base32 form (a string of letters A–Z and digits 2–7, typically 16–32 characters).

That activation code is the only thing the gateway needs. With it plus the current UTC time, anyone (or any program) can compute the 6-digit code IBKR expects at login. No phone, no app, no human. Your phone authenticator and this gateway both hold the same secret and produce the same code independently.

How to enable Authenticator App on IBKR

Log into Client Portal at interactivebrokers.com with your live credentials.

Top-right menu (head & shoulders icon) → Settings. In the search box on the left, type secure login, then click Secure Login System.

Click Add a Second Factor → choose Authenticator App (sometimes labelled "Soft Token" or "Mobile Authenticator App" depending on region).

IBKR shows a QR code with the Activation Code printed underneath. ⚠ Copy the Activation Code right now, before doing anything else. IBKR hides it once you click Continue and there's no "show again" button — only re-enrollment if you lose it. Treat it like a password.

Also scan the QR with a real authenticator app on your phone (Google Authenticator, Authy, 1Password, Yubico Authenticator — any of them). This is your manual fallback if the activation code ever gets lost or revoked from the gateway.

Click Continue. IBKR asks you to type the current 6-digit code from your authenticator app to prove enrollment succeeded. Type it; the method is now enrolled.

Keep IB Key (or another second factor) enrolled too. Don't make Authenticator App your only method. If you lose the activation code and the gateway loses it too, you'd need IBKR's account-recovery process, which can take days.

Verifying it works

Log out of IBKR Client Portal completely.
Log back in with your live username + password. After submitting, IBKR shows a "Select Second Factor Device" page (because you now have both IB Key and Mobile Authenticator App enrolled).
Pick Mobile Authenticator App; type the current 6-digit code from your phone app; you should land in the portal.

Using your live account with this gateway

From the CLI

Run node cli/ibkr.js and pick live:

── Sign in ──
Mode [paper/live] (default 'live'): live
Username: your live username
Password: *************

  Live accounts must have IBKR's "Authenticator App" 2FA enabled.
  Paste the activation code (base32 secret) IBKR showed you when
  you enrolled. Not the 6-digit code — the secret.
Activation code: ********************************
  · launching chromium…
  · selecting "Mobile Authenticator App" (value=4)
  · generating TOTP code
  · filling TOTP code
✓ signed in as your-user (mode=live)
  brokerage: authenticated=true connected=true

The activation code is saved to ~/.ibkr-cli/session.json (file mode 0600). Every subsequent run is silent — the CLI re-derives the current 6-digit TOTP from the stored secret, fills it in, and you're back in without ever touching your phone.

From the web console

Sign in to the console with your Google account. Create a new connection, choose mode Live. The connection form requires three fields:

Username — your live IBKR username.
Password — your live IBKR password.
Activation Code — the base32 secret from enrollment above. Required for live mode; the form rejects submission without it.

The activation code is stored in GCP Secret Manager — never plaintext in Firestore, never in logs. The gateway reads it each time IBKR drops the session and re-auths automatically. You can rotate or remove the secret from the connection page at any time.

Security

The activation code is at-rest credential material. Anyone with the file can log into your live account, indefinitely, until you re-enroll on IBKR.
On the CLI: stored in ~/.ibkr-cli/session.json, file mode 0600. Fine for a single user's laptop. Not fine if that laptop is shared or backed up to a public cloud / git repo / Time Machine destination you don't trust.
On the gateway: stored in GCP Secret Manager. Access mediated by the service account; the value never appears in logs, in Firestore, or in API responses.
If you suspect a leak: Client Portal → Settings → Secure Login System → remove Authenticator App → re-add. The old secret is invalidated immediately, and you'll get a new activation code to paste into the CLI / web console.

Rotating the activation code

Remove Authenticator App in the IBKR portal.
Add it again. Copy the new activation code.
Update wherever you stored the old one:
- CLI: re-run node cli/ibkr.js, choose live, paste the new activation code — it overwrites the old one in session.json.
- Web console: open the connection, click Rotate Activation Code, paste the new one. The gateway replaces the Secret Manager value and the next re-auth uses the new secret.

Last verified end-to-end against a real live IBKR account in May 2026. If IBKR has moved the menu, search for "secure login" or "two-factor" inside Account Settings.