Customise the auth journey

Learn about the customisation options for TrueLayer's auth dialog.

You can customise your user's authentication journey. Some customisation options are restricted to regulated clients or agents of TrueLayer, and some are only available on our Scale or Enterprise pricing tier.

 Customise the user experience

The auth journey a user goes through can be configured by passing different parameters in your auth link. There are 3 possible flows:

  1. Full flow: You just add a button on your app, we create the remaining pages for the Auth Dialog flow.
  2. DIY bank selection: Implement your own bank selection UI. Direct the user to the auth dialog once they've selected a bank.
  3. Direct bank authentication: Implement your own bank selection and consent collection UIs. Direct the user straight to their banking app.

Flow type

About this flow

Bank selection

Consent collection

Full flow

Great for getting started and MVPs. Minimal development investment required to start accessing user's data.

Handled by the auth dialog

Handled by the auth dialog

DIY bank selection

Best UX for most implementations. Users stay in your app for longer and are only redirected for the regulated activity of collecting user consent to share data.

Handled in your app or website

Handled by the auth dialog

Direct bank authentication

Best UX for clients with their own AIS license. Users don't interact with any TrueLayer UIs. The flow is: your app > bank > your app.

Handled in your app or website

Handled in your app or website

Full flow

Full flow is the default implementation. If you provide none of the optional URL parameters in your auth link, the auth dialog will handle everything and return the user to your redirect URL with a code you can exchange for an access token.

DIY bank selection

When you provide the provider_id parameter in an auth link, the bank selection screen will be skipped. This requires you to implement a bank selection screen yourself. You can use our providers endpoint to populate this screen and capture a valid provider_id.

Direct bank authentication

🚧

Regulator's license required

You must have permission from the FCA in order to use direct bank authentication for UK providers. You need similar permission from an EU regulator to use direct bank authentication for EU providers.

If you have the required licenses, please contact us and we will enable the API for your client_id

Direct bank auth requires an API call to generate the auth link. In addition to all the parameters required for the DIY bank selection flow, you need to provide a consent_id. This uniquely identifies a record of the user consent you collected prior to redirecting the user to the bank.

curl --request POST \
     --url https://auth.truelayer.com/v1/authuri
     --data-raw '{
        "response_type": "code",
        "client_id": "{$client_id}",
        "redirect_uri": "https://console.truelayer.com/redirect-page",
        "scope": "accounts offline_access",
        "provider_id": "ob-monzo",
        "consent_id": "123"
    }'

You'll get a response like the following:

{
  "result": "https://verify.monzo.com/open-banking/authorize?client_id=oauth2client_abc123&request=ey...&state=au..."
  "success": true
}

Customise the user interface

The dialog's UI can be customised to fit with your brand.

On the Scale plan and the Enterprise plan, you can further customise parts of the Auth Dialog including colours, some copy elements, or setting a cancellation_uri directly from our console.

Certain configuration options are not available to agents of TrueLayer.

Customisation

Configured via

Available to agents

Notes

App name
This is the name of your app or customer facing brand

Console

:x:

Logo
The logo of your customer facing brand

Console

:x:

Colour palette
Your brand paletter

Console

:white-check-mark:

On our free Develop plan, only the secondary colour is customisable. You'll need to upgrade to a paid plan to change the primary or tertiary colours.

Cancellation URI
Where users will be directed if they select cancel and choose not to share data

Console

:white-check-mark:

Description
Explain to the user why you're asking them to share data. The more specific the better

Console

:white-check-mark:

Language
Render the dialog in one of 6 languages

Auth link URL parameter language_id

:white-check-mark:


Did this page help you?