A Go library for authenticating with the Interactive Brokers (IB) Client Portal Web API Gateway.
This library provides a pure Go implementation of the authentication flow used by the IB Gateway API. It handles:
- SRP (Secure Remote Password) authentication
- Two-factor authentication (SMS, IB Key, TOTP)
- Cookie management for session persistence
- RSA encryption for secure communication
go get github.com/bishop-bot/ibgateway-gopackage main
import (
"fmt"
"log"
"github.com/bishop-bot/ibgateway-go"
)
func main() {
// Create authenticator with TOTP second factor
authConfig := ibgateway.AuthConfig{
Username: "your_username",
Password: "your_password",
BaseURL: "https://localhost:5000",
SecondFactorMethod: ibgateway.TOTP,
TOTPSecret: "YOUR_TOTP_SECRET", // e.g., from Google Authenticator
}
authenticator, err := ibgateway.NewAuthenticator(authConfig)
if err != nil {
log.Fatal(err)
}
defer authenticator.Close()
// Authenticate
if err := authenticator.Authenticate(); err != nil {
log.Fatal(err)
}
// Finalize the authentication
if err := authenticator.Finalize(); err != nil {
log.Fatal(err)
}
fmt.Println("Authentication successful!")
fmt.Printf("Is Paper Trading: %v\n", authenticator.IsPaper())
}The library can also be imported from the auth subpackage:
import "github.com/bishop-bot/ibgateway-go/auth"
authConfig := auth.AuthConfig{...}
authenticator, _ := auth.NewAuthenticator(authConfig)authConfig := ibgateway.AuthConfig{
Username: "your_username",
Password: "your_password",
BaseURL: "https://localhost:5000",
SecondFactorMethod: ibgateway.IBKeyAndroid, // or ibgateway.IBKeyIOS
OCRASecret: "YOUR_OCRA_SECRET",
OCRAPin: "YOUR_PIN",
OCRACounter: 2,
}authConfig := ibgateway.AuthConfig{
Username: "your_username",
Password: "your_password",
BaseURL: "https://localhost:5000",
SecondFactorMethod: ibgateway.SMS,
}After authentication, you can use the session to make API requests:
session := authenticator.GetSession()
// Make a request to get account info
resp, err := session.Get("/v1/api/portfolio/accounts")
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
// Read and parse the response
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))The library supports the following two-factor authentication methods:
| Constant | Description |
|---|---|
ibgateway.SMS |
SMS-based verification code |
ibgateway.TOTP |
Time-based one-time password (Google Authenticator, etc.) |
ibgateway.IBKeyAndroid |
IB Key on Android device |
ibgateway.IBKeyIOS |
IB Key on iOS device |
Creates a new Authenticator instance.
func NewAuthenticator(config AuthConfig) (*Authenticator, error)Configuration for authentication:
| Field | Type | Required | Description |
|---|---|---|---|
Username |
string | Yes | IB account username |
Password |
string | Yes | IB account password |
BaseURL |
string | Yes | Gateway URL (e.g., https://localhost:5000) |
SecondFactorMethod |
string | No | Default: SMS
|
OCRASecret |
string | For IB Key | OCRA secret for IB Key auth |
OCRAPin |
string | For IB Key | PIN for IB Key auth |
OCRACounter |
int | For IB Key | Counter for IB Key auth |
TOTPSecret |
string | For TOTP | TOTP secret (base32 encoded) |
| Method | Description |
|---|---|
Authenticate() |
Perform the full authentication flow |
Finalize() |
Complete authentication with dispatcher request |
GetSession() |
Get the HTTP session for API requests |
GetSessionToken() |
Get the session token |
IsPaper() |
Check if authenticating to paper trading |
Close() |
Close the authenticator and release resources |
The library provides specific error types:
-
ibgateway.AuthenticationError- General authentication failures -
ibgateway.TwoFactorError- Two-factor authentication errors -
ibgateway.MaxLoginAttemptsError- Too many failed login attempts
if _, ok := err.(*ibgateway.MaxLoginAttemptsError); ok {
// Handle max login attempts error
}The library manages cookies automatically. The session token can be retrieved and stored for later use:
// Get session token after authentication
token := authenticator.GetSessionToken()
// Store token for future use
// (In production, store securely)
// Reuse token in a new session
session, _ := ibgateway.NewSessionManager("https://localhost:5000")
session.SetSessionToken(storedToken)- Go 1.21 or higher
- IB Gateway running and accessible
- IB account with API access enabled
- Download and install IB Gateway from Interactive Brokers
- Enable API access in the Gateway settings
- Configure the API port (default: 5000)
- Enable two-factor authentication in your IB account
- Never hardcode credentials in your code
- Use environment variables or a secrets manager
- The library uses TLS with certificate verification disabled by default (IB Gateway uses self-signed certs)
- Store session tokens securely
MIT License
