Track auth journey events

Understand how far a user got through an auth journey.

📘

This feature is in public beta

We're still developing this feature and would love to hear your feedback for how it could be improved.

You can view events from an auth journey using a unique tracking_id. Below is the list of events that can be tracked.

Event NameEvent Description
dialog_startedThis is the first step in the auth journey and is captured when the provider selection screen is launched.
provider_selectedThis event is captured when a provider is selected
consent_grantedThis event is captured when the user clicks 'allow' on the consent screen.
provider_auth_startedThis event is captured when the provider authorisation starts
provider_authorizedThis event is captured when the provider authorisation is successful
code_exchangedThis event is captured when a code is returned to the client application

How to implement tracking

To track events, include the tracking_id query parameter in your auth link. The value of tracking_id must be unique for each auth link.

Below is an example auth link with the tracking_id query parameter.

https://auth.truelayer.com?response_type=code&client_id=foobarltd-123xyz
 	&redirect_uri=https://foobarltd.com/truelayer-redirect
 	&scope=info%20accounts%20balance
 	&provider_id=ob-monzo&providers=uk-ob-all
 	&tracking_id=901be708-3452-435a-a47e-00c87a9f250b

Retrieve the events

Once the auth journey is complete, you can retrieve the sequence of events that occurred with a single request.

🚧

Events data retention

We only store the tracked events for a period of 60 days.

An access token with the client credentials grant is required to authenticate.

curl --request POST \
     --url https://auth.truelayer.com/connect/token \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "grant_type": "client_credentials",
     "scope": "tracking",
     "client_id": "YOUR_CLIENT_ID",
     "client_secret": "YOUR_CLIENT_SECRET"
}
'

Then use the access token to fetch events for a given tracking_id

curl --request GET \
     --url 'https://client-tracking.truelayer.com/v1/tracked-events?tracking_id=${TRACKING_ID}' \
     --header 'Authorization: Bearer ${access_token}'
     --header 'Accept: application/json'