Skip to main content
Correlation ID is currently in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. To learn more about Auth0’s product release cycle, read Product Release Stages. To participate in this program, contact Auth0 Support or your Technical Account Manager.

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.
Auth0 provides the capability to trace authentication transactions with Correlation ID. This tracking capability can reduce support response time and provide you with multi-system tracking downstream of authentication events. The 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
You can use Correlation ID with Universal Login, Universal Login Page Templates, Email Templates, SMS Templates, Custom Error Pages, Flows, and Auth0 Actions.

Configure correlation ID

Values for correlation_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)
Pass the correlation_id parameter in the authorizationParams object to append the unique ID to the authorization URL, similar to the following example:
const { loginWithRedirect } = useAuth0();
loginWithRedirect({
  authorizationParams: {
    // Appends "&correlation_id=..." to the URL for tracking
    correlation_id: "YOUR_CORRELATION_ID"
  }
});

Universal Login

All Universal Login flows support correlation_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:
// 1. Call the Management API (SDK v5 syntax)
const { data: logs } = await management.logs.list({
  per_page: 100,
  sort: 'date:-1'
});
// 2. Filter the array client-side to find your ID
const transactionEvents = logs.filter(log =>
  log.references?.correlation_id === "YOUR_CORRELATION_ID"
);
console.log(`Found ${transactionEvents.length} events for this transaction.`);

Login Page Template

If you customize your login experience with Universal Login Page Templates, add the correlation_id to your template to track authentication events with custom login. Example
The following sample demonstrates correlationId: "{{correlation_id}}" added to the {%- auth0:widget -%}.
<!-- Example: Injecting the ID into a client-side script -->
<!-- Note: {{ }} is Liquid template syntax evaluated server-side by Auth0, not documentation placeholders -->
<script>
  window.addEventListener("load", function () {
    const loginContext = {
      application: "{{application.name}}",
      // Access the correlation_id directly via Liquid syntax
      correlationId: "{{correlation_id}}"
    };

    console.log("Tracking Context:", loginContext);
    // You can now pass loginContext.correlationId to your analytics tool
  });
</script>

Email Templates

You can include correlation_id in Email Templates to help trace authentication events that trigger email notifications, such as password resets or verification emails. Example
The following sample demonstrates {{correlation_id}} added to an email template body.
<p>If you did not initiate this request, please ignore this email.</p>
<p>Tracking reference: {{correlation_id}}</p>

SMS Templates

You can include correlation_id in SMS Templates to trace authentication events that trigger SMS notifications, such as MFA challenges. Example
The following sample demonstrates {{correlation_id}} added to an SMS template.
Your verification code is: {{code}}. Ref: {{correlation_id}}

Custom Error Pages

You can include correlation_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. Example
The following sample demonstrates {{correlation_id}} added to a custom error page template.
<h1>{{error | escape}}: {{error_description | escape}}</h1>
<p>If you need support, reference this ID: {{correlation_id}}</p>

Auth0 Actions

With Auth0 Actions Signup and Login Triggers, use the event object to log events to third-party services or pass the events to downstream APIs. The following event objects support correlation_id: Example
The sample Post-Login Action demonstrates how to extract the correlation_id from the event object.
exports.onExecutePostLogin = async (event, api) => {
  console.log('PostLogin Action Start');
  const correlation_id = event.transaction?.correlation_id;
  // Check if correlation_id exists
  if (correlation_id) {
    console.log(`Correlation ID found: ${correlation_id}`);
  } else {
    console.log('No correlation_id found in transaction');
  }
  console.log('PostLogin Action End');
};

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 the context 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.