Data API authentication

Learn how to connect to your user's account with our authentication process.

📘

Overview

This guide explains how to 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 FCA policies, GDPR, and PSD2.

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

Once a user successfully authenticate 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 credential with the bank that lasts 90 days. Without this scope, you'll have access to data for 60 minutes only.

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?