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
providers you must include either
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.
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
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 the console as described:
Code redirect: Your user's browser is redirected to the
redirect_uricontrolled by the client with a
code, the requested
scope, and the optional
access_token: The application exchanges the
codereceived with a short-lived
access_token(and optionally a
refresh_tokenif the scope
offline_accesswas requested) making a HTTP POST to the TrueLayer authorisation server including the application
Access Data API: The application can use the obtained
access_tokento access data on behalf of the user. An
Authorizationheader must be provided to access any endpoint of the Data API.
Renew the access_token: After the short-lived
access_tokenexpires (1 hour by default or provider specified) a new
access_tokencan be obtained using the
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
Your client ID
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.
Space-separated list of requested permissions.
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.
While optional, we recommend that you use the
The email address of the end user
This 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.
Space-separated list of providers to present to the user for selection. If not provided, the dialog defaults to
To enable Mock Bank, our fictitious bank for testing, include provider
If supplied provider selection will be skipped.
Use the providers endpoint for a list of supported provider IDs
If set to
Space-separated list of provider ids to be hidden in the authentication dialog
Sets the language for auth dialog. If not specified, auth dialog defaults to the user's browser language before falling back to English.
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.
Base64Url encoded string of the SHA256 hash of the
PKCE requires a
code_verifier. This is a cryptographically random string using the characters
0-9, and the punctuation characters
~ (hyphen, period, underscore, and tilde), between 43 and 128 characters long.
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_challenge_method parameters must be supplied.
Updated 13 days ago