Recurring Access
Your customer connects once in the widget; your backend refreshes the data for as long as the access lives
A Financial Rider session can be used once or for good. The difference is not a different product — it is whether the session keeps a token of the credentials your customer signed in with.
How it works
Two phases, on two APIs: the onboarding happens once, in the widget, because only your customer can type their credentials; every refresh after it is a server-to-server call your backend makes on its own schedule.
Everything after the first connection is the Direct Executions API, server to server. Exchanging a ticket, refreshing, checking and revoking a token are calls your backend makes with your application secret — Exchange a ticket, Initiate with a token, Check a token and Revoke a token. The widget and its API play no part in them: your customer is only needed in the widget, to connect or to reconnect.
Create the session with recurring access
Create Session with settings.tokenized_access: true. The answer carries a ticket — shown there and nowhere else, so store it with the session.
Your customer connects their banks
Exactly as in any session: consent, pick a bank, sign in. Every connection that finishes keeps a token of the credentials it signed in with — at the banks that support it.
Exchange the ticket, once per connection
Get Session Results lists the connections by id. For each one, Exchange a ticket with that id as execution_id and the session’s ticket. What comes back is that bank’s token_id and token_key — store both halves, and treat the key like a password: it is never shown again. If you already held a token for that same account and customer, it comes back renewed: your list of connections explains it.
Refresh from your backend, whenever you need to
Initiate with a token runs that bank again with the stored credentials, and its results are read like any direct execution’s — the financial position or one family at a time. No widget, no customer: a call from your backend, as often as your process needs.
A token is locked to what the session asked for. One application, one bank, one customer_id and the features the session read. A refresh may ask for fewer features, never for more: widening the scope means a new session — which renews the same token —, because reaching more of somebody’s data should require their credentials again.
Your list of connections
What you show your customer — BBVA, connected; Santander, connected — is a list of connections, and token_id is the identifier to keep it by. A connection is one bank account of one of your customers: the same application, the same bank, the same customer_id and the same account. It has one token for life.
So a customer who presses connect on a bank they already connected does not get a duplicate: the entry you already have is renewed. token_id is the field that never changes: a renewal revokes nothing — it keeps the token and gives it a new key —, so match on it and nothing else; there is nothing to compare yourself, not locking_hash, not the bank’s name. Managing your customers’ connections is the practical guide: what to keep per connection, and the connect, reconnect and remove flows of your screen.
What it needs
- The
login:tokenized_accesscapability, for a production application — see Capabilities. A sandbox session tokenizes without it. - A bank whose engine supports it. Each engine says so in
tokenized_access, on List your engines — banks typically do, as telcos and utilities do: sources worth reading again. A session with recurring access offers only the banks that can, so your customer never connects one you could not refresh. Filters that leave none are refused at Create Session with400 no_engines_available_for_tokenized_access, and a named bank that cannot with422 engine_not_available_for_tokenized_access. - Somewhere safe for the token key. Half of the access is yours, and only yours: we keep the credentials encrypted and a verifier of your key, never the key. Credential Tokenization explains the design.
Recurring access in production needs Tokenized access
Every application can tokenize in sandbox. In production, asking for tokenized_access without the Tokenized access capability is refused with 403 and insufficient_capabilities@login:tokenized_access — no ticket is issued and nothing is created.
When the access has to be renewed
A refresh runs without your customer, so anything only a person can do ends it instead of waiting:
- A second factor. If a bank asks for one during a refresh, nobody is there to answer it — a run started with
customer_interaction_available: falseends instead of pausing. Challenges & MFA describes the pause and its answers. - Credentials that stopped working. A changed password, or an account the bank locked, leaves the token locked: Check a token says so, and retrying only makes the bank count more failures.
- Time. A token expires 90 days after the last exchange, whether it was used or not.
In every case the answer is the same: a new Financial Rider session with tokenized_access, where your customer connects that bank again. Exchanging its ticket at Exchange a ticket — on the Direct Executions API — renews the token you already have — the same token_id, a new key, a new expiry — so your list of connections keeps the same entry. Plan the renewal before the expiry date rather than after the first failed refresh — Stored credentials has the token’s lifecycle, its statuses and how to revoke it.
Revoking is your customer’s right, and two calls. When they withdraw their consent or leave your service, Revoke a token for every bank, and delete the executions that used it. Both are immediate and neither needs us.