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.

Tracking-event API request

The request have to be authenticated using another access_token, which is specifically created using tracking scope, and client_credentials as the grant_type.

🚧

Events data retention

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

  1. Generate a new separate access token with the following values
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"
}
'
  1. Then use the created tracking access token to authorize the /tracked-events endpoint for a given tracking_id. See the example below:
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'

Tracking-event API response example:

{
    "results": [
        {
            "name": "dialog_started",
            "time": "2024-02-14T16:30:53.9932322Z",
            "flow_id": "afss-bSwX44BeBZwV4vEvZfW5i--3VwpTTDmLeJGUxyHY6ug",
            "reauth": false
        },
        {
            "name": "provider_selected",
            "time": "2024-02-14T16:31:15.4072047Z",
            "flow_id": "afss-bSwX44BeBZwV4vEvZfW5i--3VwpTTDmLeJGUxyHY6ug",
            "reauth": false,
            "provider_id": "ob-monzo"
        },
        {
            "name": "provider_auth_started",
            "time": "2024-02-14T16:31:16.1414827Z",
            "flow_id": "afss-bSwX44BeBZwV4vEvZfW5i--3VwpTTDmLeJGUxyHY6ug",
            "reauth": false,
            "provider_id": "ob-monzo"
        },
        {
            "name": "consent_granted",
            "time": "2024-02-14T16:31:16.8349439Z",
            "flow_id": "afss-bSwX44BeBZwV4vEvZfW5i--3VwpTTDmLeJGUxyHY6ug",
            "reauth": false,
            "provider_id": "ob-monzo"
        }
    ]
}