Auth link basics

The first step in the authentication process is to redirect the end user with a properly formatted link to TrueLayer's authorization server. A valid auth link will result in a new auth session being created in TrueLayer's backend and the user being immediately redirected to our auth dialog.

📘

What is an auth link?

The auth link is a URL that directs users to TrueLayer's auth dialog, via our auth server. Your auth link is specific to your integration.

If the provider used for the authentication is already known, it can be supplied with an optional provider_id parameter in order to skip the selection.

Note that even if you include a provider_id parameter, the intended provider must still be included in the providers parameter. For example, if you use provider_id=ob-monzo, under providers you must include either uk-ob-all or ob-monzo.

Clients with regulatory permission to collect user consent themselves (for example, an AISP license from the Financial Conduct Authority in the UK), can use the alternative Direct Bank Authentication process to generate a link for the user to follow.

Generating an auth link

You can generate an auth link using the auth link builder in console.

You might need to construct auth links dynamically in your application depending on which parameters you want to use.

https://auth.truelayer.com/\
  ?response_type=code\
  &client_id=foobarltd-123xyz\
  &redirect_uri=https://foobarltd.com/truelayer-redirect\
  &scope=info%20accounts%20balance
https://auth.truelayer.com/\
  ?response_type=code\
  &client_id=foobarltd-123xyz\
  &redirect_uri=https://foobarltd.com/truelayer-redirect\
  &scope=info%20accounts%20balance \
  &state=foo-usr-id-6789hjkl
https://auth.truelayer.com/\
  ?response_type=code\
  &client_id=foobarltd-123xyz\
  &redirect_uri=https://foobarltd.com/truelayer-redirect\
  &scope=info%20accounts%20balance \
  &provider_id=ob-monzo \
  &providers=uk-ob-all

Auth link parameters

Url Parameter

Description

Required

client_id

Your client ID

:white-check-mark:

redirect_uri

This is where the user is redirected when they exit the auth flow. This must exactly match one of the redirect URIs registered against your client ID in console.

:white-check-mark:

scope

Space-separated list of requested permissions.

:white-check-mark:

state

A value used to maintain state between the request and callback. This allows you identify the user or session when users are redirected after auth.

response_type

Must be code

:white-check-mark:

providers

Space-separated list of providers to present to the user for selection. If not provided, the dialog defaults to providers=uk-oauth-all uk-ob-all.

To enable Mock Bank, our fictitious bank for testing, include provider uk-cs-mock.

provider_id

If supplied provider selection will be skipped.

Use the providers endpoint for a list of supported provider IDs

response_mode

If set to form_post the code will be submitted via form POST instead of a query string encoded GET redirect.

disable_providers

Space-separated list of provider ids to be hidden in the authentication dialog

language_id

Sets the language for auth dialog. If not specified, auth dialog defaults to the user's browser language before falling back to English.

Supported values: en (English), es (Spanish), it (Italian), fr (French), de (German), zh_CN (Chinese - Simplified).

tracking_id

Used in combination with Auth Journey Analytics (private beta). Allows you to query for analytics events from the auth dialog session to debug auth journeys.

v

Use v=3 to activate the new version of TrueLayer’s auth dialog for an individual session.

code_challenge

Base64Url encoded string of the SHA256 hash of the code_verifier

code_challenge_method

Must be S256.

Optional PKCE flow

By default auth links initiate a regular OAuth2 authorization_code flow. Optionally, you may choose to use a PKCE flow which is a more secure option for mobile and javascript based implementations.

PKCE requires a code_verifier. This is a cryptographically random string using the characters A-Z, a-z, 0-9, and the punctuation characters - . _ ~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.

The code_verifier is held on to by the client and passed on a back channel during final code exchange. To initiate PKCE flow the code_challengeand code_challenge_method parameters must be supplied.


Did this page help you?