Account-First Model
Identity model, environments, session flow, and account-scoped paths.
Finatic is account-first: your company authenticates with API keys, the user connects a broker in Connect, and your app reads or trades only against financial account IDs they granted.
See Account model for the short overview.
Identity model
| Concept | In your app |
|---|---|
| Company workspace | API keys, sessions, webhooks — dashboard accountId / companyAccountId |
| Financial account | accountId on /api/v1/accounts/{accountId}/... routes and SDK calls |
| Provider connection | Internal to Finatic — do not store or expose to customers |
Persist company account ID, your user ID, and granted financial accountId values. Do not build on legacy beta connectionId or user_broker_connection_id.
End-to-end flow
- Backend creates a session and portal link (API key).
- Browser opens Connect with the one-time token.
- User signs in to the broker and selects accounts.
- Connect creates grants (read, optional trading).
- Wait until data is ready — poll session sync status or use per-account webhooks (
account.grant.created,account.sync.succeeded). No session-level “all ready” webhook yet. - Read or trade via account-scoped routes, e.g.
/api/v1/accounts/{accountId}/positions.
Backend: session and portal link
Browser: Connect and first reads
Backend: check sync readiness
Environments
| Environment | Behavior |
|---|---|
live | Real broker auth and data (including broker paper accounts) |
sandbox | Finatic synthetic test data only |
Do not mix sandbox and live account IDs.