Managing your TrueLayer tokens: the do’s and don’ts

Profile Photo
João Cadidé, Quality, training & knowledge specialist
12 Jun 2019
Background Image

We often receive queries about tokens and how to manage them. To make the best out of our Data API, here’s a handy guide of best practices when using tokens.

What are tokens anyway?

One of the most fundamental parts of TrueLayer’s Data and Payments API are tokens. Thanks to our proprietary technology and approach to security, end-users do not share their bank credentials with third-party applications. Ever. Instead, you will obtain a pair of tokens, that will unlock the power of access to bank data.

Tokens are encoded strings that contain unreadable information to the human eye. When a user connects their bank account to your app, TrueLayer will provide you with two tokens: access_token and refresh_token. Your access_token may look like this:

Product Demo

The access_token used by TrueLayer is created based on an open standard called JWT. They contain non-sensitive information about the user such as consents given, expiry dates, provider, credentials_id, etc.

Keeping your tokens safe and up-to-date guarantees continuous access to your user’s data (where consent has been provided) and perfect functionality of your application!

The 🐺 lone wolf dies but the pack survives

Once your end-user gives TrueLayer and your application permission to access their data offline, you will get a code that you will need to exchange for TrueLayer tokens. Our tokens come in pairs. Let’s see them:

The access_token allows you to access the user’s data on their behalf. They are short-lived (up to one hour) and must be used in every request.

When the access_token expires, the refresh_token is needed to renew both tokens. You will get a new pair that will allow you to carry on retrieving data — with the user’s consent.


Exchange the code with a pair of tokens

✅ Store your tokens securely in your database, always in the same row


❌ Wait longer than 5 minutes to exchange your code — they expire very quickly!

❌ Store the matching access_token and refresh_token separately.

❌ Share tokens with anyone.

Multiple accounts = multiple tokens?

Let's take our fictional user John Doe 🕵. He really enjoys testing banks and credit cards and is a member of Natwest (with a current account, savings and a credit card), Monzo (current account and pots), Barclays (Current account), and American Express.

Being hard for him to track all of his money, he decides to use our demo application, PiggyBank that uses TrueLayer’s Data API as the middle-man. John then connects all his accounts above using TrueLayer’s Data API and leaves PiggyBank to handle all the connections.

To ensure that the tokens are not mixed up or lost, here’s how PiggyBank handles the relationship between the tokens:

John Doe’s Natwest identity will generate one TrueLayer credentials_id which identifies this account in our system. You can see his credentials_id below:

One credentials_id is associated with one set of credentials (username, membership number, password, PIN, etc) which will then have an associated pair of access_token and refresh_token.

The access_token will give you access to all John’s Natwest accounts (Current, Savings and Credit Card).

John’s connection with Monzo will give a different pair of tokens that will be associated with another credentials_id. This access_token gives then access to John’s Monzo Current Account and Pots.

Have a look at the diagram below to clarify:



✅ Associate one user’s connection to a bank with a matching pair of tokens (access_token and refresh_token)

✅ Use the same access_token to retrieve data from different accounts and cards within the same connection


❌ Use the same tokens for different connections of the same user. E.g.: John’s Natwest token can’t be used to retrieve John’s Monzo data.

One pair to rule them all

Access tokens are needed to do all sorts of requests: balance, transactions, accounts, info, cards and so on.

As long as it is still valid, the same access_token gives you access to all requests supported. Therefore, there is no need to save the same pair of tokens in more than one place. This creates more complexity and could result in errors such as old tokens being left behind, wrong tokens for the wrong credentials, etc.


✅ Save your pair of tokens in one place only

✅ Make sure that other parts of your application read your tokens from the same place


❌ Save the same tokens in multiple places

Keep them fresh

Attention: as of September 2019, refresh tokens do not change between requests. The access_tokens will still change. Read more information in our new blog post: Refresh tokens — Refreshed.

For security reasons, access_tokens expire very shortly (up to one hour, depending on the provider). You will need to renew them periodically and make sure to keep only the most recent pair in your database.

Here are some errors that might occur if old tokens are used:

  • invalid_grant

  • Token expired

  • Internal error

Tokens that are badly managed might lead to end-users having to re-authenticate with the bank provider 🏦.


✅ Replace the old access_token and refresh_token with the new ones after every refresh

✅ Renew tokens periodically or prior to a big batch of requests


❌ Replace only one of the tokens after a refresh

❌ Keep old tokens in your database

❌ Forget to refresh tokens periodically

These are the best practices recommended by TrueLayer when it comes to managing your tokens. Have you got any further questions? Take a look at our FAQs and contact our Client Care team; we’re always happy to help you get the best out of our APIs!

Want to work with us? Say hi 👋, we’re hiring!

Grow with us
We are systems builders, design thinkers and product crafters. Together, we build intelligent financial infrastructure that puts fintech at people's fingertips.
View open roles
20 May 2024

How to successfully reverse chargebacks

13 May 2024

Charting Europe’s path to payments leadership

hand folding a debit back with a X in the background
10 May 2024

Chargeback prevention: 7 ways to reduce chargebacks

Categories to explore