IBKR Account Admin — Setup Checklist

STEP 1Create dedicated automation username

The developer needs a username that only the automated tooling uses. Reason: IBKR allows only one active session per username across all IBKR services — if your personal login on TWS or the mobile app shares a username with the automation, every time you open the app, the automation gets disconnected.

1. Log into Client Portal as the account owner.
2. Navigate to:
   Settings → Users & Access Rights → Add User
   (or "Add a Login" — wording varies by region)
3. Create a new user with these settings:
   • Name: something like "API Automation" or "Dashboard Reader."
   • Permissions: read-only / view-only is sufficient if the tool will only read positions and market data. If the tool will eventually place trades, give trading permissions for the relevant asset classes; otherwise restrict.
   • Two-factor authentication: required by IBKR. Use IBKR Mobile (the IBKR app, not Google Authenticator) if possible — it's the path that works best with automated session-keepalive.
4. Confirm the new user is created and has its own username (write it down — you'll need it later).
5. Do not use this username for any human login, including the mobile app or the desktop. Treat it as machine-only.

STEP 2Set subscriber status (pro vs non-pro)

This affects how much market data costs. By default, IBKR classifies everyone as professional. Professional data rates are roughly 10× non-professional rates.

1. Log into Client Portal as the automation user (not the account owner).
2. Navigate to:
   Settings → Market Data Subscriptions → Subscriber Status
3. Answer the eligibility questionnaire honestly.
   • An individual using the account for personal investing is usually non-professional.
   • An entity / firm / company account is usually professional (no waiver).
4. Submit and digitally sign.

If you are unsure which category applies, ask IBKR support before clicking — wrong status can lead to back-billing or subscription suspension.

STEP 3Enable Market Data API Acknowledgement

This is the single most common reason new IBKR integrations return empty market-data responses. Without this enabled, none of the subscriptions you pay for will flow through the API.

1. Still logged in as the automation user, navigate to:
   Settings → Market Data Subscriptions → Market Data API Acknowledgement
   (sometimes "Market Data API Subscriber Agreement")
2. Read the agreement.
3. Select Yes.
4. Digitally sign the form.

STEP 4Purchase exchange entitlements

The developer will tell you exactly which exchanges to subscribe to. You will need to confirm this with the developer before clicking — the wrong subscription wastes money and the right one is often counter-intuitive.

For this account, the developer's likely target list (will confirm before you buy):

• US equities (NYSE / NASDAQ / ARCA)
• Frankfurt (Xetra / FWB)
• London Stock Exchange / AIM
• Toronto Stock Exchange (TSX)
• Johannesburg Stock Exchange (JSE)
• ASX (Sydney)

For each one:

1. Navigate to:
   Settings → Market Data Subscriptions → Add Subscription
2. Find the exchange in the list.
3. Read the description carefully — look for the word "API," "off-platform," or "Cboe One" / similar non-TWS-only signals. If the description says "TWS only" or "for use in Trader Workstation only," it will not work for the dashboard.
4. Confirm the per-month cost matches what the developer quoted.
5. Subscribe.

Activation is usually within the same trading session, occasionally next-business-day.

STEP 5Generate First Party OAuth credentials

This is the auth path the developer is using. It is the one that does NOT require a third-party Compliance approval — because you (the account owner) are authorizing your own tool to access your own account, not a third-party vendor.

The Self Service Portal is where this happens. If you have never used it, ask IBKR Customer Service to enable Self Service Portal access for your account — there is usually a short approval step (~1 business day).

Once Self Service Portal access is confirmed:

1. Log into Self Service Portal (separate URL from Client Portal — IBKR Customer Service will send the link when they enable access).
2. Navigate to:
   OAuth → Manage Consumer Keys
   (or similar — wording varies)
3. Generate a new consumer key for first-party use. Label it clearly (e.g. "Internal Dashboard 2026-06").
4. Download or copy the following items as they are generated. All four are sensitive — handle as you would a password:
   • Consumer key (a short string)
   • Access token (a longer string)
   • Access token secret (a longer string — the most sensitive of the four)
   • DH (Diffie-Hellman) parameters (a longer file or text block — sensitive)
5. Generate or upload an RSA private key. The Self Service Portal will either generate one for you (most common) or ask you to upload a public key whose private half you keep.
   • If it generates one: download the .pem file. This is the most sensitive item in the whole process — treat it like the account password.
   • If you generate locally: keep the private .pem secure; only the public part goes to IBKR.

STEP 6Confirm account metadata

The developer needs these data points to set up the tooling correctly. None of them are sensitive — these are settings you can paste into a chat message or email.

1. Base currency of the account (USD, ISK, EUR, etc.)
   Client Portal → Account Information → Base Currency
2. Account structure: single standalone, or master account with linked sub-accounts?
   Client Portal → Account Information → "Linked Accounts" / "Account Hierarchy"
3. IBKR entity / region: IBKR LLC, IBKR Ireland, IBKR UK, IBKR Hong Kong, IBKR Singapore, IBKR Canada, etc. The daily server-reset window depends on this.
   Client Portal → Account Information → "Account Holder Information" → "Entity"
4. Account number (the 7-character ID that starts with U, DU, or similar). Not strictly sensitive but identifies the account in API responses.

STEP 7What to send back

Once steps 1–6 are complete, the developer needs the following to start building. Use the secure transfer channel the operator/developer specifies — do not email these items.

What NOT to send

Things you might be asked later

After the developer starts building, two operational items may come back to you within the first few weeks:

1. Approving 2FA prompts during setup. The first time the automated tool logs in, IBKR's mobile app may send a push asking you to confirm. Approve it. Once the session is established, subsequent re-auths during the daily server-reset window may also need approval. The developer will tell you when to expect these.
2. Adding or removing exchange subscriptions. Once the dashboard is running, you might decide a market is no longer worth the per-month cost, or that a new market needs coverage. Either way, it's a small Client Portal change — the developer will tell you what to click.

Troubleshooting

If the developer reports empty market-data responses:

• Most common cause: Step 3 (Market Data API Acknowledgement) is not toggled to Yes.
• Second most common: a subscription is in "TWS only" mode rather than the "API-enabled" tier.
• Third: subscriptions purchased on the account owner username, not the automation user username. Subscriptions attach to the username — buy them while logged in as the automation user.

If the developer reports authentication errors:

• Confirm the RSA private key was transferred without corruption (line endings on Windows can mangle .pem files).
• Confirm the automation user has not been locked out by failed logins.
• Confirm 2FA prompts are reaching your phone and are not being silently denied or auto-dismissed.

If the developer reports intermittent disconnects:

• Check whether someone (you, a family member, an accountant) logged into the account using the same username — this kicks the automation off. Confirm the automation username is human-untouched.

After setup is complete

This guide is a one-time setup. Once the developer confirms the tooling is working, you should not need to revisit any of these steps. The next time you'll hear from the developer is either (a) an exchange subscription change, (b) a 2FA approval prompt, or (c) a security incident (in which case the developer will tell you exactly what to revoke and how).

Thank you for working through this — IBKR's setup landscape is unusually deep, and getting it right up front saves the entire integration cost in surprises later.