Create a connection

Learn how to connect to your user's account with connections.

📘

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 redirect 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 kickoff the process of accessing their bank data. When a user clicks on your auth link, they'll be taken to our auth dialog. Your auth link is specific to your integration.

The auth dialog is the user-facing interface that guides users through the process of sharing 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 section.

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"
}

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

📘

One time access vs long-lived access

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

Country

offline_access connection lifetime

No offline_access connection lifetime

United Kingdom
Australia

90† days
365 days

60 minutes
24 hours

Starling bank in the UK allows users to extend the life of their connection for another 90 days from the Starling app. This means you might notice you can continue to access data from Starling for longer than 90 days without having to re-authenticate. Starling will deprecate this feature by September 30th 2022.

After the short-lived access_token expires, a new access_token can be requested using a refresh_token. The default expiration period of an access_token is 1 hour.

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"
}

Did this page help you?