General Data API concepts

This page includes an explanation for connections and scopes as they appear in Data API v1.

Connections

A connection is the term for the relationship between your application and your user’s bank, facilitated by TrueLayer. Once your user has granted consent and undergone the authentication process, there will be a valid connection, identified by an access token that can be used to fetch account information from their bank.

An active connection is made up of two elements:

• an active consent
• an active authentication.

To use any of TrueLayer's AIS powered products, you must first create a connection.

Consent

Open banking is built upon data access being shared by an end user who has given full and informed consent. The consent is given to and stored by the licensed Account Information Service Provider (AISP). If you are not a licensed AISP, the consent is given to TrueLayer.

Consent has a limited length of validity, and will expire. The length of validity varies because different countries set different rules.

When a consent expires you won’t be able to access data until your user reconfirms their consent.

Authentication

Once your user has granted consent, TrueLayer can start the authentication process with their bank. Once they have successfully finished the authentication process, TrueLayer will receive and securely store the information needed to access your user's bank information upon request.

Authentications may expire, depending on the open banking standard and the individual bank being accessed.

In general, authentications expire after a set period of time. The duration of validity varies but is usually 90 days. The exception is the UK where authentications are open-ended and never expire. Instead, it is consent that needs to be reconfirmed at least every 90 days to continue data access.

Connection lifecycle

A connection moves through four statuses: authorization_required, authorized, active, and inactive.

1. You receive the user's consent. The connection has the authorization_required status.

2. The user authorises with their bank. The connection becomes authorized and you receive a code.

3. You exchange the code for an access_token (and a refresh_token if you requested offline_access). The connection becomes active and stays active for 90 days.

4. You can extend the connection with /connections/extend — during the active period or after it lapses.

5. If you don't extend, the connection becomes inactive after 90 days and you can't retrieve data until the user reconfirms consent.

There's no endpoint to check a connection's status directly, but you can check when a connection expires with the /data/v1/me endpoint.

For more information, go to Create a connection.

Scopes

A list of space-separated scopes need to be included in the scope parameter when you create an auth link or implement a direct bank authentication link. In the auth link builder in Console, scopes are referred to as Permissions.

Scopes represent the categories of data you're asking the user to share as well as how long you'll be able to access the user's data. The auth dialog uses scopes to determine what information to display to the user when collecting consent. Ultimately scopes limit the Data API endpoints you are authorised to access.

How scopes combine

accounts and cards are the base scopes. balance and transactions are modifiers. This means that you must combine balance and transactions with accounts or cards to use them (for example, accounts balance or cards transactions).

direct_debits and standing_orders must be combined with accounts.

Product permissions

You can also enable scopes for TrueLayer products. They are enabled by default in the Sandbox environment, but to enable them for production, contact Support.