Handling sessions

Any service accepts and returns an optional session object that can be passed to consecutive calls of the same or other services to possibly avoid authentication or authorization steps or at least speed things up.

While it might still work, a session object should be considered obsolete after passing it to a service.

Long-lived connection data

While sessions expire after a short amount of time and thus are not meant to get persisted, there is also the concept of long-lived connection data. In case credentials get persisted on the client for recurring access, it is recommended to store and update connection data with them whenever a service returns some. Just like sessions, passing such data can avoid authentication and authorization steps and speed things up.

Whenever a service returns connection data, overwrite any copy you already hold. The data can change on any successful call, and an outdated copy may keep working for a while before it stops. If you rely on connection data for later access, updating it every time is required, not optional — a stored copy that is never refreshed will eventually fail.

Successful service calls return connection data as an encrypted blob. You can therefore also synchronize it between multiple frontends or pass it to your backend services.

Some services also accept connection data instead of credentials. If the service then fails with an InterruptError (see Handling errors), it requires user interaction to complete. Start the service again with credentials in that case and store the connection data it returns.

Backend refreshes

In your backend, a refresh client runs such services with connection data, so you can refresh account information without the user being present. For recurring refreshes, see also Recurring consents.

Banks may limit access while the user is not in session. If the user is in session, e.g. because your app triggered the refresh, signal it to the refresh client.

Redirects

Note that the session object typically does not help with redirect authentication steps (unless redirect scraping is enabled on the connection for you). Make sure that cookies stay available between redirect steps, so that providers might pick up their session again.

Recurring consents

For regular access to account information, you can opt in to recurring consents. The client SDKs provide interfaces to set a respective flag on service calls. Set it on the interactive calls that establish or re-establish the connection — that is, calls made with the user’s credentials, where a consent is actually granted. It has no effect on background refreshes, which reuse the consent carried in the connection data, nor on calls made without credentials. Whenever a consent is required to access certain resources and no recurring one is already available, the service will request a recurring one with maximum permissions.

Make sure to handle connection data properly, as they carry the necessary consent data.

By default, the service requests a one-time consent with targeted, minimum permissions.

As some providers display detailed consent information, minimal one-time consents are ideal for single-use cases, while recurring consents make sense when onboarding users for regular access.

When establishing a recurring consent, the service requests a validity of up to 180 days. Once a consent has expired, the next call that relies on its connection data initiates a new consent or fails with InterruptError (see Handling errors).

Independently of consent validity, retrieving transactions dated more than 90 days in the past requires a fresh strong customer authentication — the service cannot rely on an existing consent for that range. With the user present this means an additional SCA; on a non-interactive refresh it is not possible, and the call reports that user interaction is required.

Access limits

Banks limit how often a connection may be refreshed without the user present, typically to four times per day. Exceeding this limit does not return stale data: the call fails with AccessExceeded (see Handling errors). The limit applies to non-interactive access only; calls made with the user present are not subject to it.