Generate an auth link

An auth link is the first step in creating a connection. Creating a connection happens in three stages:

Start the auth journey — you send your user to an auth link.
Handle their return — after they authorise with their bank, they're
redirected back to your app with a code.
Exchange the code — you swap the code for an access_token and start
calling the Data API.

This page covers stage 1: how to build the auth link. The auth link is a URL that directs users to TrueLayer's auth dialog, via our auth server. It's specific to your integration. A valid auth link creates a new auth session and immediately redirects the user to the auth dialog.

Each auth link is used a single time — create a new one whenever a user connects or reconnects.

Build your auth link

You build an auth link by adding query parameters to TrueLayer's authorisation server URL. This section takes you through it from scratch.

Before you start

You need two things from <a href="https://console.truelayer.com/"target="_blank">Console:

Your client_id — from your app's settings.
A registered redirect URI — where TrueLayer returns the user after they connect. It must be added to your app in Console before you use it. For testing, add and use https://console.truelayer.com/redirect-page, which displays the code in your browser.

The anatomy of an auth link

Every auth link starts with the same base URL, followed by query parameters. For example:

https://auth.truelayer.com/?parameter1=value1&parameter2=value2

The required parameters

These four are all you need for a working link:

Parameter	What to put
`response_type`	Always `code`.
`client_id`	Your `client_id` from Console.
`redirect_uri`	A redirect URI registered against your app in Console.
`scope`	A space-separated list of the data you're requesting (see Scopes).

We also strongly recommend state — any value you choose (for example, your own ID for the user).

TrueLayer returns it to you on the redirect so you can tell which user just connected. It helps reconcile requests that are stateless by nature.

Build the auth link

Start with the base URL and response_type, then add each parameter:

https://auth.truelayer.com/?response_type=code

https://auth.truelayer.com/?response_type=code&client_id=yourapp-abc123

https://auth.truelayer.com/?response_type=code&client_id=yourapp-abc123&redirect_uri=https://console.truelayer.com/redirect-page

https://auth.truelayer.com/?response_type=code&client_id=yourapp-abc123&redirect_uri=https://console.truelayer.com/redirect-page&scope=info%20accounts%20balance

https://auth.truelayer.com/?response_type=code&client_id=yourapp-abc123&redirect_uri=https://console.truelayer.com/redirect-page&scope=info%20accounts%20balance&state=user-1234

That's a complete, working auth link. Because parameter values can't contain raw spaces, the scopes are joined with %20 (URL encoding).

Test it with Mock Bank

To try the link end to end without a real bank, add providers=uk-cs-mock to make the Mock Bank available:

https://auth.truelayer.com/?response_type=code&client_id=yourapp-abc123&redirect_uri=https://console.truelayer.com/redirect-page&scope=info%20accounts%20balance&state=user-1234&providers=uk-cs-mock

Open it, choose Mock Bank, and log in with a set of Mock Bank credentials (for example, john / doe). You'll be redirected to your redirect URI with a code — now exchange it for an access token.

🚧
Can I embed an auth link in a modal using an inline frame?
No. TrueLayer uses Content-Security-Policy headers that prevent auth links
being embedded in an iframe, for security reasons. As an alternative, open a new
browser window — but test it, as pop-up blocking can be an issue.

Preselect a provider (optional)

If you already know which bank the user wants, add provider_id to skip the bank selection screen. Use the /providers endpoint to find valid provider IDs.

Even when you set provider_id, the same provider must also appear in providers. For example, with provider_id=ob-monzo, include either uk-ob-all or ob-monzo in providers.

📘
Collecting consent yourself?
Clients licensed to collect user consent themselves (for example, an FCA AISP licence in the UK) can use Direct Bank Authentication to send users straight to their bank instead of through the auth dialog.

Common mistakes

redirect_uri not registered or not an exact match to Console (including
https:// and any path) — the most common cause of errors.
Raw spaces in scope — always encode them as %20.
Reusing a link — generate a new one for every connect/reconnect.
Missing response_type=code — it's required and must be exactly code.

Optional PKCE flow

By default, auth links initiate a regular OAuth2 authorization_code flow. Optionally, you can use a PKCE flow — a more secure option for mobile and JavaScript-based implementations.

PKCE requires a code_verifier: a cryptographically random string of the characters A-Z, a-z, 0-9, -, ., _, ~, between 43 and 128 characters long. The client holds the code_verifier and passes it on a back channel during the final code exchange. To initiate a PKCE flow, supply the code_challenge and
code_challenge_method parameters.