Account Grants and Connect

Learn how Finatic Connect creates account grants and how your backend checks authorization and data readiness.

Connect is where the end user signs in to their broker, reviews your company’s request, picks accounts, and approves scopes. Your app works with grants and accountId values — not raw broker credentials.

What a grant does

Action	Effect
Create grant	Your company gets read (and optional trade) access to one financial account
Update grant	Change read/trade flags or data clusters
Revoke grant	Remove your company’s access and revoke the linked compliance consent record; user’s broker login stays

Full disconnect	User removes the broker connection and stored data is cleared

Create access only through Connect (user consent). List, update, and revoke existing grants via the company API after the user has granted.

Connect flow (token)

Backend uses its API key in X-API-Key to mint a separate short-lived one-time token.
Browser starts the Client SDK session with that token.
Browser opens Connect.
onSuccess(userId) reports that the portal user was linked to the session; it is not grant completion.
User authenticates, selects accounts, and approves scopes.
Connect emits account.grant.created through the Client SDK onEvent callback after the API persists each grant.
Wait until data is ready (poll or webhooks).

Check readiness after Connect

Server — the released server facades do not yet wrap session sync status, so poll the REST endpoint with your API key:

const response = await fetch(
 `https://api.finatic.dev/api/v1/sessions/${encodeURIComponent(sessionId)}/sync-status`,
 { headers: { 'X-API-Key': process.env.FINATIC_API_KEY! } },
);
if (!response.ok) throw new Error(`Sync status failed: ${response.status}`);

const result = await response.json() as {
 success?: { data: { status: string; accounts: Array<{ accountId: string }> } };
};
if (result.success?.data.status === 'ready') {
 const accountIds = result.success.data.accounts.map((account) => account.accountId);
}

Client — after Connect, list accounts with sync status (session sync poll is server-only):

Or subscribe to account.grant.created and account.sync.succeeded webhooks — see Webhooks.

The Client SDK portal onEvent callback also receives account.grant.created, account.grant.updated, and account.grant.revoked lifecycle events. These iframe events tell the browser what happened in the current Connect flow; backend webhooks provide durable server-to-server delivery.

List grants (company API)

Resource scopes

Cluster	Enables
`ACCOUNTS`	Account list and details
`BALANCES`	Cash and buying power
`POSITIONS`	Positions and lots
`TRANSACTIONS`	Activity history
`ORDERS`	Order history and trading (with `canTrade`)

Set canTrade only when you place orders. Read-only apps should leave it false.

No-token Connect

End users can open Connect without your company session to manage grants across companies or fully disconnect a broker. Use that for user-owned settings screens — not as a substitute for your API key.

Store after Connect

Your user ID
Granted accountId values (and grantId for revoke/webhooks)
Trace IDs from API responses and webhooks

Portal onSuccess does not mean a grant exists, and account.grant.created does not mean every balance or position is current. Poll sync status or use account.sync.succeeded before assuming data is fresh.