Customise the auth journey

You can customise the authentication journey your users go through. This page covers the three possible auth flows and the options available to customise the auth dialog UI.

📘
Availability
Direct bank authentication requires a regulator's licence (see below). Brand colour customisation requires a paid pricing plan. Some options — such as setting a cancellation URI — require TrueLayer to configure on your behalf.

Customise the user experience

The auth journey a user goes through is configured by the parameters you pass in your auth link. The table below summarises the three available flows.

📘
Provider selection must always come before consent collection. This is a regulatory requirement — it applies in the UK under OBIE open banking guidance, and equivalent rules apply in the EU under that framework.

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 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 consent to share data.	Handled in your app or website	Handled by the auth dialog
Direct bank authentication	Users don't interact with any TrueLayer UIs. The flow is: your app → bank → your app. Requires an AIS licence in the EU.	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 handles everything and returns the user to your redirect URL with a code you can exchange for an access token.

DIY bank selection

When you include the provider_id parameter in an auth link, the bank selection screen is skipped. This requires you to implement your own bank selection UI. Use the /providers endpoint to retrieve a list of valid providers and capture a provider_id to pass in the auth link.

Direct bank authentication

🚧
Regulator's licence required (UK/EU)
You must have permission from the FCA to use direct bank authentication for UK providers. You need equivalent permission from an EU regulator for EU providers.
Contact us with your client_id and we'll enable the API for your account.

With direct bank authentication, users never interact with any TrueLayer UI — the entire flow is: your app → bank → your app.

To generate the auth link, make a POST request to /v1/authuri. In addition to the parameters required for DIY bank selection, you must provide a consent_id — a unique identifier for the user consent you collected before redirecting the user to their bank.

Direct bank auth request

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

Response

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

Redirect your user to the result URL. They'll authenticate directly with their bank, then be redirected back to your redirect_uri with a code you can exchange for an access token in the usual way.

Customise the user interface

If your contract includes it, you can customise the auth dialog to match your brand. You can configure these settings in Console — most options are in Product UI > General Settings or Data UI, depending on what you're customising.

Customisation	Configured via	Notes
App name — The name of your app or customer-facing brand	Console — Product UI > General Settings	Applies to both Data and Payments UIs.
Logo — The logo of your customer-facing brand	Console — Product UI > General Settings	Applies to both Data and Payments UIs. Upload as a square PNG between 100×100 and 1500×1500 px.
Colour palette — Your brand colours	Console — Data UI	On the free Develop plan, only the secondary colour is customisable. Upgrade to a paid plan to change the primary or tertiary colours.
Cancellation URI — Where users are directed if they cancel and choose not to share data	Contact TrueLayer to configure	This is not self-serve. Provide your `client_id` and the desired URI to TrueLayer and we'll configure it for you.
Description — Explain to users why you're asking them to share data	Console — Data UI	We recommend selecting one of the available use cases from the dropdown. These are localised into all the languages the auth dialog supports, so your description is automatically translated.
Language — Render the dialog in a specific language	Auth link URL parameter `language_id`	If not specified, the dialog defaults to the user's browser language. Supported values: `en` (English), `es` (Spanish), `it` (Italian), `fr` (French), `de` (German), `pl` (Polish), `pt` (Portuguese), `sv` (Swedish), `nl` (Dutch).

Browser support

The auth dialog is built to work best on:

Chrome
Edge
Firefox
Safari