Prerequisites
To use
correlation_id, you must have:- Auth0 Universal Login configured: Correlation ID is available in Universal Login flows.
- An application capable of generating unique IDs: Your application should be able to generate UUIDs or transaction IDs. (Example:
txn_12345_xyz, session IDs, or order IDs)
If
correlation_id isn’t available in your authorization requests, your tenant may not have this feature enabled.correlation_id parameter adds a unique identifier generated by your application to the authorization URL. This ID is automatically recorded, allowing you to track and filter events in Auth0 Tenant Logs.
Correlation ID persists through the following events:
- Signup
- Login
- Multi-Factor Authentication (MFA) enrollment and challenges
- Password reset
Configure correlation ID
Values forcorrelation_id have the following limitations:
- Allowed characters: Alphanumeric and special characters matching
/^[-\w.*~@+/:]{1,64}$/. - Maximum length: 64 characters
- Must not contain any Personally Identifiable Information (PII)
correlation_id parameter in the authorizationParams object to append the unique ID to the authorization URL, similar to the following example:
Universal Login
All Universal Login flows supportcorrelation_id. Once you pass the correlation ID value to the /authorize endpoint, authentication events generate tenant logs with the correlation ID you can use for tracking. Use the Management API SDK to retrieve and filter recent events to isolate a specific transaction.
Example The following sample call uses the Management API SDK to retrieve the latest authentication events. Then, it filters locally to isolate a specific event:
Login Page Template
If you customize your login experience with Universal Login Page Templates, add thecorrelation_id to your template to track authentication events with custom login.
ExampleThe following sample demonstrates
correlationId: "{{correlation_id}}" added to the {%- auth0:widget -%}.
Email Templates
You can includecorrelation_id in Email Templates to help trace authentication events that trigger email notifications, such as password resets or verification emails.
ExampleThe following sample demonstrates
{{correlation_id}} added to an email template body.
SMS Templates
You can includecorrelation_id in SMS Templates to trace authentication events that trigger SMS notifications, such as MFA challenges.
ExampleThe following sample demonstrates
{{correlation_id}} added to an SMS template.
Custom Error Pages
You can includecorrelation_id in Custom Error Pages to surface the tracking reference directly on error pages, making it easier for users to report issues and for your support team to trace the failed transaction.
ExampleThe following sample demonstrates
{{correlation_id}} added to a custom error page template.
Auth0 Actions
With Auth0 Actions Signup and Login Triggers, use theevent object to log events to third-party services or pass the events to downstream APIs.
The following event objects support correlation_id:
- Pre-user-registration
- Post-login
- Post-challenge
- Post-change-password
- Custom email provider
- Custom phone provider
- MFA Notification send-phone-message
- Credential Exchange
The sample Post-Login Action demonstrates how to extract the
correlation_id from the event object.
Forms
You can use Correlation ID in Forms and Flows. Forms allows you to customize signup and login with custom logic you create in Flows. To use Correlation ID in Forms and Flows, use thecontext object in the Flows editor to add the correlated events variable, {{context.transaction.correlation_id}}, to your logic. To learn more, read Variables and helper functions.