Create a connection

This guide explains how to create a new connection and generate access tokens to make authenticated calls to the Data API.

It walks through the process of:

1. generating an auth link to take the user through the auth journey
2. handling the user's redirection back to your app after they've authorised with their bank
3. making an authenticated API call to access the user's data

Connection authorisation lifecycle

There is no endpoint you can use to check the status of an existing connection, but this diagram shows the lifecycle and statuses that a connection moves through.

A connection can have four statuses: authorization_required, authorized, active, and inactive. This is the flow of a connection through these statuses:

1. You receive the user's consent for you to access their financial data.
   The connection now has the authorization_required status.
2. The user authorises the connection with their banking provider.
   The connection now has the authorized status and you receive a code as a callback.
3. You exchange the code for an access_token. If the connection has the offline_access scope, you can exchange this for a refresh_token.
   The connection now has the active status, and remains active until 90 days have passed since the connection was created.
4. Optionally, you can extend the connection by making a POST request to the /connections/extend endpoint, if the user gives consent. You can do this during the 90 days it's active, or after it becomes inactive after 90 days.
5. If don't extend the connection it enters the inactive status after 90 days. This means you can't retrieve data for the user.
   However, you can optionally extend the connection with a request to the /connections/extend endpoint if the user reconfirms consent. You can do this while the connection is still active, or after it becomes inactive.

Open banking regulations mean that a user's consent to grant access to their financial data can last a maximum of 90 days, after which the connection expires. You can check when a connection will expire with the /data/v1/me endpoint.

Auth link and auth dialog

An auth link is a URL you provide to your user to start the authorisation process. When a user clicks on your auth link, they'll be taken to our auth dialog, where they can give consent to connect their bank account via TrueLayer. Your auth link is specific to your integration.

The auth dialog is the UI that guides users through the process of consenting to share their banking data. It's simple to integrate, works on all modern browsers and devices, and is compliant with government policies including FCA, GDPR, and PSD2 in the UK and CDR in Australia.

You can generate an auth link in the Console's auth link builder.

Once a user successfully authenticates with their bank, they'll be redirected back to the redirect_uri URL you specified in your auth link. This redirect link will contain a code in the URL parameters.

📘

Tip for first-timers

Use the default redirect link (https://console.truelayer.com/redirect-page) to begin with. It will render the code nicely in the browser so you can quickly generate an access token. Implement your own redirect URL once you've generated an access token and have everything working end-to-end.

Exchanging a code for an access token

Once a code is obtained, it can be exchanged for a short-lived access_token.

curl -X POST \
    -d grant_type=authorization_code \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d redirect_uri=${redirect_uri} \
    -d code=${code} \
    https://auth.truelayer.com/connect/token

{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "REFRESH-TOKEN-HERE"
}

📘

invalid_grant

If you try to exchange a code that is not active, you receive an invalid_grant error.

The most common specific reasons that this error occurs are:

• Over 5 minutes have elapsed since the code was generated
• The code has already been successfully exchanged for an access_token

To fix this, you will need to generate a new code.

Make an authenticated call to Data API

You can use this access_token to make an authenticated call to the Data API. The example below lists all the accounts a user has chosen to share with you.

curl -H "Authorization: Bearer ${access_token}" \
  https://api.truelayer.com/data/v1/accounts

Optional: Renew an access token with a refresh token

Your access_token will expire after 1 hour. After that, depending on the scopes you have enabled, you may be able to request a new access_token using a refresh_token.

📘

One-time access vs long-lived access

You'll only be able to renew access tokens that have the offline_access scope enabled. This scope instructs TrueLayer to create a long-lived credential with the bank. Without this scope, you'll only have access to data for an hour.

If you've enabled the offline_access scope, there will be a refresh_token in the response alongside the access_token. As long as you use it at least once within the first 30 days after you receive it, you can use the refresh_token to renew the access_token as many times as you want for up to 90 days.

curl -X POST \
    -d grant_type=refresh_token \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d refresh_token=${refresh_token} \
    https://auth.truelayer.com/connect/token

{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": "JWT-EXPIRY-TIME",
  "token_type": "Bearer",
  "refresh_token": "REFRESH-TOKEN-HERE"
}