Concepts
| Credential | Looks like | Lives | Where | Use |
|---|---|---|---|---|
| Secret key | fb_sk_live_… / fb_sk_test_… | until you roll it | your server only | exchange for a server token |
| Restricted key | fb_rk_… | until you roll it | your server only | like a secret key, limited to chosen scopes |
| Publishable key | fb_pk_live_… / fb_pk_test_… | until you roll it | browsers | identifies your platform to the SDK; grants nothing |
| Server token | JWT | short | your server | call the GraphQL API |
| Client secret | es_…_secret_… | 15 minutes, single use | your server → browser, once | start an embed session |
| Embed token | JWT, typ: embed | 1 hour by default | inside FinBaze's iframe only | run the component's operations |
| Headless token | JWT, typ: headless | 1 hour by default | your page | run the headless hooks |
From secret key to server token#
POST /v2/oauth2/token with grant_type=client_credentials and client_secret=<key>. A restricted key can ask for a subset of its scopes with scope.
From client secret to embed token#
- Your backend calls
createEmbedSessionand returnsclientSecretto the page. - The SDK's hidden controller iframe (on FinBaze's origin) calls
exchangeEmbedSession. The exchange consumes the secret atomically: a second use fails withEMBED_SECRET_USED. - The embed token is held in memory in that iframe and handed to component iframes over a private channel. It never reaches your page, local storage or cookies.
- Before the token expires the SDK asks
fetchClientSecretfor a new secret and repeats. There are no refresh tokens: your backend decides, every time, whether the user may continue.
A chain of refreshes ends after embed.max_chain_hours (12 by default); the user then needs a session minted without previousSessionId.
What a token can do#
An embed token is pinned to one company, one user and the components in the session. It can only run FinBaze's own operations for those components, and only the features you left on. Everything else is refused (EMBED_OPERATION_NOT_ALLOWED). See embed security model.
Revoking keys#
Revoking or rolling a secret, restricted or publishable key refuses new token exchanges at once. Server and user tokens already minted with that key stop working on the next request: immediately on the API server that handled the revocation and normally within a second on the others. When the internal message between servers is lost, a server's cache still expires after 10 seconds, so plan for up to 10 s in which an old token may still be accepted. The same applies to suspending your platform, disabling a platform user and removing a user's access to a company.
Rate limits#
Limits count requests per rolling minute and are shared by all API servers. Over a limit the API answers HTTP 429 with code RATE_LIMITED; wait for the next minute and retry with backoff.
| What | Counted per | Limit per minute |
|---|---|---|
| GraphQL requests with a server or user token | key the token was minted with | 600 |
| GraphQL requests with an embed or headless token | platform user | 600 |
POST /v2/oauth2/token with a platform key | key (by its lookup id), failed attempts included | 60 |
createPlatformUserToken | key | 300 |
createPlatformCompany | key | 30 (it calls the company registers) |
createEmbedSession | key | 600 |
exchangeEmbedSession | publishable key | 600 |
exchangeEmbedSession | IP address | 30 |
The same limits apply in the sandbox and in live. If you need more for a key, ask FinBaze: a key can carry its own request limit.
Revoking embed sessions#
revokeEmbedSession(id) ends one session; revokeEmbedSessionsForUser(platformUserId) ends all of a user's. Disabling a user or removing their access does this for you. Revocation takes effect within 15 seconds.