Account Grants and Connect

How Connect creates grants and how your backend checks 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 creates a session (X-API-Key).
Backend creates a portal link for that session.
Browser opens Connect with the one-time token.
User authenticates and selects accounts.
Grants are created for your company.
Wait until data is ready (poll or webhooks).

Check readiness after Connect

Server — poll session sync status:

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.

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

Initial Connect success does not mean every balance or position is current yet — poll sync status or use webhooks before assuming data is fresh.