Skip to content
Finatic
Sign Up

Connecting Brokers

Open Finatic Connect, authorize a brokerage connection, create account grants, and verify access from your application.

Use Connect so users sign in to their broker, pick accounts, and grant your company access. Store financial accountId values from granted accounts — not broker passwords, provider connection IDs, or your companyAccountId.

Open Connect

1type AccountSummary = { 2 accountId: string; 3 syncStatus?: string; 4}; 5 6await finatic.openPortal({ 7 mode: 'dark', 8 onSuccess: (userId) => { 9 // The portal linked the Finatic user to this session. 10 // This callback does not mean a grant or account data is ready. 11 console.log('Portal user:', userId); 12 }, 13 onEvent: async (eventName, payload) => { 14 if (eventName !== 'account.grant.created') return; 15 16 console.log('Durable grant created:', payload); 17 const accounts = await finatic.v1.listAccounts<AccountSummary[]>({ 18 includeSyncStatus: true, 19 }); 20 const readyAccounts = 21 accounts.success?.data.filter( 22 (account) => account.syncStatus === 'ready', 23 ) ?? []; 24 console.log('Ready accounts:', readyAccounts); 25 }, 26 onError: (error) => console.error(error), 27});

Client SDK flow — mint a short-lived one-time token on your backend, pass that token (never the API key) to the browser, initialize the Client SDK, and call openPortal() with separate callbacks for portal identity and durable lifecycle events.

Server SDK flow — keep the API key on your backend, call startSession() and getPortalUrl(), then redirect the browser to that URL. You do not pass the Client SDK one-time token separately in this flow. The returned short-lived portal URL contains its own portal token, so treat the complete URL as sensitive and do not log or persist it. The API key stays on your backend.

onSuccess(userId) means the portal linked the Finatic user to the session. It does not prove that the user selected an account, a durable grant exists, or broker data is ready. Handle account.grant.created through onEvent, then check sync readiness before making account-scoped reads.

Verify grants

1type AccountSummary = { 2 accountId: string; 3 syncStatus?: string; 4}; 5 6const result = await finatic.v1.listAccounts<AccountSummary[]>({ 7 includeSyncStatus: true, 8}); 9if (result.success) { 10 const ready = result.success.data.filter( 11 (account) => account.syncStatus === 'ready', 12 ); 13 console.log(ready.length, 'ready account(s)'); 14}

Persist financial accountId values from the account list only after a grant event. Use each account's syncStatus, or poll the session sync-status endpoint from your backend, before reading balances, positions, transactions, or orders.

Portal options and troubleshooting

Optional openPortal props include email, mode, onSuccess, onEvent, onError, and onClose. Institution availability is configured in the Finatic console under Connect → Catalog, not via SDK parameters.

  • Portal won't open — check token, init(), and browser console errors.
  • No grant event — confirm the user selected an account and approved access; broker authentication alone is not completion.
  • Grant exists but data is not ready — inspect syncStatus or poll GET /api/v1/sessions/{sessionId}/sync-status from the backend using the session id returned by startSession() / start_session(), not companyAccountId. Do not use a fixed sleep.
  • Connection fails — confirm broker is on the Integrations page and credentials are valid.

Next