Account Model
How your company, end users, and granted brokerage accounts relate — aligned with FDX consent patterns.
The integration model is account-first, following the same consent ideas as the Financial Data Exchange (FDX): an end user connects a broker, chooses what to share, and your company only sees what they approved.
Who is who
Your company is the Finatic customer. You authenticate with API keys, create sessions, open Connect for users, and receive webhooks.
The end user owns their broker login. They connect through Finatic Connect and decide which brokerage accounts your company can access.
A financial account is one brokerage account (for example, a margin or IRA account at Alpaca). Your API and SDK calls use its accountId.
An account grant is the user's approval for your company to read or trade that account. Grants define scopes such as balances, positions, orders, and optional trading.
You integrate against granted accountId values, not broker connection credentials. Connection details stay between the user and Finatic.
Typical Connect flow
- Your backend creates a session and portal link using your company API key.
- The user opens Connect, signs in to the broker, and selects accounts.
- Account grants are created for your company with the scopes the user approved.
- Your backend waits until broker data is ready — see Waiting for data after Connect below.
- Your app reads or trades via account-scoped routes, e.g.
GET /api/v1/accounts/{accountId}/positions.
For code samples and identity fields to persist, see Account-First Model.
Waiting for data after Connect
Granting access and having data ready are not the same moment. After Connect, Finatic pulls initial broker data in the background.
Polling: GET /api/v1/sessions/{sessionId}/sync-status until aggregate status is ready.
Webhooks: Subscribe to account.grant.created and account.sync.succeeded per account if your backend already handles webhooks. See Webhooks.
There is no single session-level “all accounts ready” webhook yet — only per-account events plus the session poll endpoint.
Who manages grants
| Action | Where |
|---|---|
| Create access (user picks accounts and scopes) | Connect only — requires end-user consent |
| List, update, or revoke an existing grant | Company API — after the user has already granted |
To add a new account or scopes the user never approved, send them through Connect again.
Sandbox vs live
| Environment | Use when |
|---|---|
sandbox | Synthetic test data; no live broker I/O |
live | Real broker auth and data (including broker paper accounts) |
Do not mix sandbox and live account IDs. See Sandbox Environment.
Next
- Connections and grants — how Connect creates access
- Webhooks — notify your backend when data changes
- FDX — industry account and consent standards