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 start 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 UI 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.

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 with a refresh token

Countryoffline_access connection lifetimeNo 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.

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