Create a connection

📘

Overview

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

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.

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": "JWT-EXPIRY-TIME",
  "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"
}