Generate an auth link

The first step in the authentication process is to redirect the end user with a properly formatted link to TrueLayer's authorisation 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. Re-authentication requires a new auth link.

📘

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.

Each auth link should be used a single time, so you need to create a new one when users re-authenticate.

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 or a client acting under Outsourced Service Provider (OSP) or Consumer Data Right (CDR) representative models in Australia), can use the alternative Direct Bank Authentication process to generate a link for the user to follow.

Generating an auth link

🚧

Can I embed an auth link in a modal using an inline frame?

TrueLayer uses Content-Security-Policy headers which prevent the use of modals in the form of an iframe. We use this approach (alongside many other banks) because of security reasons.

As an alternative to using a modal, you can open a new browser window but you must test this approach to check if browser pop-up blocking is an issue.

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.

Your user's browser is redirected to our authorisation server using a link that includes the application's client_id, redirect_uri (already authorised for the client) and a scope parameter defining the requested permissions to the user. A state argument is optional but is strongly recommended. The state argument helps reconcile requests that by their nature are stateless.

You can build your authentication link in Console as described:

1. Code redirect: Your user's browser is redirected to the redirect_uri controlled by the client with a code, the requested scope, and the optional state.

2. Exchange code with access_token: The application exchanges the code received with a short-lived access_token (and optionally a refresh_token if the scope offline_access was requested) making a HTTP POST to the TrueLayer authorisation server including the application client_id, client_secret and redirect_uri.

3. Access Data API: The application can use the obtained access_token to access data on behalf of the user. An Authorization header must be provided to access any endpoint of the Data API.

4. Renew the access token: After the short-lived access_token expires (1 hour by default or provider specified) a new access_token can be obtained using the refresh_token

https://auth.truelayer.com/\
  ?response_type=code\
  &client_id=foobarltd-123xyz\
  &redirect_uri=https://foobarltd.com/truelayer-redirect\
  &scope=info%20accounts%20balance\
  &[email protected]

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\
  &[email protected]

https://auth.truelayer.com/\
  ?response_type=code\
  &client_id=foobarltd-123xyz\
  &redirect_uri=https://foobarltd.com/truelayer-redirect\
  &scope=info%20accounts%20balance\
  &[email protected]\
  &provider_id=ob-monzo\
  &providers=uk-ob-all

Auth link parameters

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.