Generate an auth link

Redirect your user to the TrueLayer auth dialog.

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.

📘

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

🚧

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

Url ParameterDescriptionRequired
client_idYour client ID:white-check-mark:
redirect_uriThis 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:
scopeSpace-separated list of requested permissions.:white-check-mark:
stateA value used to maintain state between the request and callback. This allows you identify the user or session when users are redirected after auth.While optional, we recommend that you use the state parameter because it helps reconcile requests that are stateless by nature.
response_typeMust be code:white-check-mark:
user_emailThe email address of the end userThis field is not required for clients who are licensed to perform AIS by the FCA in the UK (or relevant equivalent regulatory body in the EU).

While this parameter is optional, we strongly advise unregulated clients to include it. We will provide at least 3 months notice before making this parameter required.
providersSpace-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_idIf supplied provider selection will be skipped.

Use the /providers endpoint for a list of supported provider IDs
response_modeIf set to form_post the code will be submitted via form POST instead of a query string encoded GET redirect.
disable_providersSpace-separated list of provider ids to be hidden in the authentication dialog
language_idSets 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), pl (Polish), pt (Portuguese), sv (Swedish), nl (Dutch).
tracking_idUsed in combination with Auth Journey Analytics (private beta). Allows you to query for analytics events from the auth dialog session to debug auth journeys.
code_challengeBase64Url encoded string of the SHA256 hash of the code_verifier
code_challenge_methodMust be S256.
country_idMust be alpha_2 country code.

If supplied country selection will be skipped and the Auth Dialog will jump straight to the provider selection for the requested country.

PKCE flow (optional)

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.

In order to use a PKCE flow, you should first be familiar with how to create your code_verifier and code_challenge, then you need to apply it in your requests.

Create a code_verifier and code_challenge

In order to use the PKCE flow, you need to first complete the following steps:

  1. Create 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.
  2. Apply a SHA-256 hash to the code_verifier to get a 64-character length string.
  3. Apply Base64 URL encoding to the hash value.
    The resulting value is your code_challenge.

You use both the code_verifier and code_challenge to further secure your requests to the auth server. The process is similar to request signing, although you can choose to generate a new code_verifier and code_challenge for every request. You should keep your code_verifier secure, as the secrecy of this secures your requests.

How to use PKCE in auth server requests

You start the PKCE flow by adding query parameters to the auth link that your user accesses. After successful authorisation, you get a code as usual. When you exchange the code for an access_token via the /connect/token endpoint, you include an additional code_verifier body parameter.

The detailed process is:

  1. Generate a code_verifier and code_challenge, as outlined above.
  2. Append the following two query parameters to the auth link you share with your user:
    1. The &code_challenge= query parameter, followed by your code_challenge.
    2. The &code_challenge_method=S256 query parameter.
      The suffix S256 confirms you used a SHA-256 to generate your challenge from your verifier.
  3. Once your user authorises the connection, store the code returned.
  4. Use the code to make a request to the /connect/token endpoint, and include an extra body parameter named code_verifier.
    This should contain the code_verifier that corresponds to the code_challenge you included in your auth link earlier.

If you follow these steps, you receive an access_token generated through the PKCE flow.

This is an example of an auth link that contains the required query parameters to initiate the PKCE flow (given you have generated a code_challenge and code_verifier correctly):

https://auth.truelayer.com/?response_type=code&client_id=testclient-123xyz&redirect_uri=https://testrequest.com/truelayer-redirect&scope=info%20accounts%20balance&[email protected]&code_challenge=5d41402abc4b2a76b9719d911017c592&code_challenge_method=S256

This is an example cURL request for the following request to the /connect/token endpoint to receive an access_token:

curl --request POST \
     --url <https://auth.truelayer.com/connect/token> \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "grant_type": "authorization_code",
  "client_id": "clientId",
  "client_secret": "clientSecret",
  "code": "code",
  "code_verifier": "8ahaa4ERupUazXhydH8fVmaIZ31BQJV1RLtpxpJ5Ah0"
}