Connecting Brokers

Learn how to connect your users to their brokerages using Finatic's secure portal.

Connecting users to their brokerages is the first step after setting up your Finatic SDK. This guide walks you through the process of securely connecting broker accounts.

Overview

Finatic provides a secure authentication portal that handles broker connections for you. Users authenticate directly with their broker through Finatic's portal, and you get access to their data through the unified API.

SDK Differences:

Client SDK (Recommended): Use openPortal() to open the portal in an iframe directly with callbacks. Best for browser-based applications.
Server SDK: Use getPortalUrl() to get a URL and redirect users. Use this for server-side applications where you need to handle redirects.

Quick Start

The fastest way to connect a broker:

// Client SDK (Recommended)
await finatic.openPortal({
  onSuccess: (userId) => {
    console.log('User authenticated:', userId);
    // IMPORTANT: Save userId to your database
  },
  onError: (error) => {
    console.error('Portal error:', error);
  },
  onClose: () => {
    console.log('Portal closed');
  }
});

Step-by-Step Guide

1. Initialize the SDK

First, ensure your SDK is initialized. See the Quick Start Guide for details.

2. Open the Connection Portal

The portal allows users to:

Select their broker
Authenticate with their broker credentials
Grant permissions for Finatic to access their data

// Client SDK (Recommended) - Opens portal in an iframe with callbacks
await finatic.openPortal({
  brokers: ['broker-id'], // Optional: filter specific brokers
  email: 'user@example.com', // Optional: pre-fill user email
  mode: 'dark', // Optional: mode ('light' or 'dark')
  onSuccess: (userId) => {
    // IMPORTANT: Save userId to your database
    console.log('User authenticated:', userId);
  },
  onError: (error) => console.error('Portal error:', error), // Optional: error callback
  onClose: () => console.log('Portal closed') // Optional: close callback
});

Important: For Client SDK (openPortal):
The userId in the success callback is the Finatic user ID for this authenticated session
You must save this userId to your database, associated with your user account
This userId is required for subsequent SDK initializations and immediate data fetch
If the user closes the portal without connecting, the success callback will not be called

3. Verify the Connection

After connecting, you can verify that users have approved access by calling getBrokerConnections(). Any connections that have been approved will appear in the response. If the array is empty, no connections were added.

// Client SDK
const result = await finatic.getBrokerConnections();

if (result.success) {
  const connections = result.success.data;
  console.log(`Found ${connections.length} broker connection(s)`);
} else {
  console.error('Failed to get connections:', result.error);
}

Troubleshooting

Portal Won't Open

Client SDK:

Ensure the SDK is properly initialized with init()
Verify you have a valid one-time token
Confirm the session was created by calling getSessionId() after init()
If using openPortal(), ensure you're using the Client SDK (FinaticConnect), not the Server SDK
Check the browser console for JavaScript errors

Server SDK:

Ensure the SDK is properly initialized with your API key
Confirm the session was created by calling getSessionId() after init()
Verify you're redirecting users to the returned URL

Connection Fails

Verify the broker is active on the Integrations page
Confirm the user has valid broker credentials
Check the error callback for specific error messages (Client SDK) or review the error response (Server SDK)

Connection Expires

Connections may expire based on broker policies
Users can reconnect through the portal
Monitor connection status regularly using getBrokerConnections()
Handle expired connections gracefully in your UI

User ID Not Saved

Always save the userId from the success callback to your database
Without the userId, you cannot access the user's broker data
If the userId wasn't saved in the callback after a successful portal login, you can retrieve it by calling getUserId()
If you lose the userId, the user will need to reconnect through the portal

Common Issues

Portal opens but user can't see brokers

Verify broker filters are correct if you're filtering specific brokers

Success callback not called

The user may have encountered an error - check the onError callback

Connections not appearing after successful connection

Wait a few seconds for the connection to sync
Call getBrokerConnections() again to refresh the list
Check the connection status - it may be pending activation

Next Steps

After connecting brokers:

Getting Data - Retrieve accounts, orders, and positions.
Error Handling - Learn error handling patterns.
Explore the API Reference - See all available broker operations.