IbkrConduit.Setup 0.3.0

Credential Setup Guide

This guide walks through generating OAuth 1.0a credentials for IbkrConduit using the ibkr-conduit-setup tool. The tool generates all required cryptographic keys, guides you through the IBKR portal configuration, and produces a JSON credential file ready for use.

Prerequisites

• .NET 10 SDK or later
• An Interactive Brokers account with Client Portal API access
• Access to the IBKR OAuth Self-Service Portal

Installation

The setup tool is a .NET tool included in the repository:

# Run directly from the project
dotnet run --project tools/IbkrConduit.Setup

Or install it globally:

dotnet pack tools/IbkrConduit.Setup
dotnet tool install --global --add-source tools/IbkrConduit.Setup/bin/Release IbkrConduit.Setup

Quick Start — Interactive Wizard

The fastest way to get set up is the interactive wizard. It walks through all four steps in sequence:

dotnet run --project tools/IbkrConduit.Setup

The wizard will:

1. Generate cryptographic keys — RSA 2048-bit signature and encryption key pairs, plus 2048-bit DH parameters (safe prime generation takes 30–120 seconds)
2. Guide portal configuration — step-by-step instructions for the IBKR OAuth page
3. Collect credentials — prompts for the access token and secret from the portal
4. Validate the connection — attempts an API call to verify everything works

All output is saved to .ibkr-credentials/ by default (a hidden directory in the current working directory).

Step-by-Step Manual Setup

If you prefer to run each step individually, use the subcommands below.

Step 1: Generate Keys

dotnet run --project tools/IbkrConduit.Setup -- generate-keys

Options:

This generates six files:

Note: DH parameter generation involves finding a 2048-bit safe prime and typically takes 30–120 seconds. This is normal and matches the behavior of openssl dhparam 2048.

Step 2: Configure OAuth in the IBKR Portal

1. Log in at https://ndcdyn.interactivebrokers.com/sso/Login?action=OAUTH
2. If this is your first time, accept the OAuth agreement (check the box, type your name, submit)
3. Check the Enabled checkbox if not already enabled
4. Enter a Consumer Key — the wizard generates one for you (9 uppercase letters, e.g. XKVMTQWLR). If running manually, you can generate any 9-letter uppercase string.
5. Upload the three public files using the upload controls on the page:
   • Public Signing Key → public_signature.pem
   • Public Encryption Key → public_encryption.pem
   • Diffie-Hellman Parameters → dhparam.pem
6. Click Generate Token at the bottom of the page
7. Copy the Access Token and Access Token Secret before leaving the page

Ignore the OpenSSL commands shown on the portal page — the setup tool already generated all required keys in the correct format.

Activation delay: Newly configured OAuth credentials can take up to a few days to become active on IBKR's API servers. The portal will generate tokens immediately, but API calls may return 401 until activation completes.

Step 3: Create the Credential File

dotnet run --project tools/IbkrConduit.Setup -- configure

Options:

If flags are omitted, the tool prompts interactively with input validation.

This produces ibkr-credentials.json in the credentials directory.

Step 4: Validate

dotnet run --project tools/IbkrConduit.Setup -- validate --credentials .ibkr-credentials/ibkr-credentials.json

If validation fails with a 401 error shortly after portal configuration, wait a day or two and try again — this is the normal activation delay.

Credential File Format

The ibkr-credentials.json file contains everything needed to authenticate:

{
  "consumerKey": "XKVMTQWLR",
  "accessToken": "...",
  "accessTokenSecret": "...(base64)...",
  "signaturePrivateKey": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
  "encryptionPrivateKey": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
  "dhPrime": "A1B2C3...(hex)..."
}

The file is typically around 4.5 KB. Key sizes are fixed (RSA 2048-bit, DH 2048-bit), so file size does not vary significantly.

Loading Credentials in Code

From a file

using IbkrConduit.Auth;
using IbkrConduit.Http;
using Microsoft.Extensions.DependencyInjection;

using var creds = OAuthCredentialsFactory.FromFile(".ibkr-credentials/ibkr-credentials.json");

var services = new ServiceCollection();
services.AddLogging();
services.AddIbkrClient(opts => opts.Credentials = creds);

await using var provider = services.BuildServiceProvider();
var client = provider.GetRequiredService<IIbkrClient>();

From a JSON string (e.g. Azure Key Vault)

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

var kvClient = new SecretClient(
    new Uri("https://your-vault.vault.azure.net"),
    new DefaultAzureCredential());
var secret = await kvClient.GetSecretAsync("ibkr-credentials");

using var creds = OAuthCredentialsFactory.FromJson(secret.Value.Value);

var services = new ServiceCollection();
services.AddLogging();
services.AddIbkrClient(opts => opts.Credentials = creds);

From environment variables

using var creds = OAuthCredentialsFactory.FromEnvironment();

Required environment variables:

Security

• Never commit ibkr-credentials.json, *.pem, or private key files to source control
• The .gitignore in this repository already excludes *.pem, .ibkr-credentials/, and .creds/
• For production deployments, store the JSON content in a secret manager (Azure Key Vault, AWS Secrets Manager, HashiCorp Vault) and load via FromJson()
• The credential file is approximately 4.5 KB — well within the 25 KB limit for Azure Key Vault secrets

Troubleshooting

Command Reference

ibkr-conduit-setup                          Run the interactive wizard (default)
ibkr-conduit-setup generate-keys [options]  Generate RSA keys and DH parameters
ibkr-conduit-setup configure [options]      Create the JSON credential file
ibkr-conduit-setup validate [options]       Test credentials against the IBKR API
ibkr-conduit-setup --help                   Show help