> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging-actions-triggers-prototype.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Learn how to use Correlation ID to track events in the authentication flow.

# Configure Correlation ID

export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
  const stageTextMap = {
    "beta": "Beta",
    "ea": "Early Access"
  };
  const stageText = stageTextMap[stage] || "a product release stage";
  const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages";
  const linkify = (text, url) => {
    return <a href={url} target="_blank" rel="noreferrer" class="link">{text}</a>;
  };
  const includeDetails = (plans, contact, terms) => {
    const hasDetails = terms || plans || contact;
    if (!hasDetails) return null;
    return <span data-as="p">
            {plans && <>This feature is available for {linkify(`${plans} plans`, "https://auth0.com/pricing")}. </>}
            {contact && "To participate, contact " + contact + ". "}
            {terms && <>By using this feature, you agree to the applicable Free Trial terms in Okta's {linkify("Master Subscription Agreement", "https://www.okta.com/legal")}.</>}
        </span>;
  };
  return <Warning>
            <span data-as="p">
                <strong>The {feature} feature is in {linkify(stageText, prsLink)}.</strong>
            </span>

            {includeDetails(plans, contact, terms)}
        </Warning>;
};

<ReleaseStageNotice feature="Correlation ID" stage="ea" terms="true" contact="Auth0 Support or your Techncial Account Manager" />

<Card title="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)

  <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
    If `correlation_id` isn't available in your authorization requests, your tenant may not have this feature enabled.
  </Callout>
</Card>

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](/docs/deploy-monitor/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:

```javascript wrap lines theme={null}
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.

The following sample call uses the Management API SDK to retrieve the latest authentication events. Then, it filters locally to isolate a specific event:

```javascript wrap lines theme={null}
// 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](/docs/customize/login-pages/universal-login/customize-templates), add the `correlation_id` to your template to track authentication events with custom login.

The following sample demonstrates `correlationId: "{{correlation_id}}"` added to the `{%- auth0:widget -%}`.

```html wrap lines theme={null}
<!-- 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](/docs/customize/email/email-templates/customize-email-templates) to help trace authentication events that trigger email notifications, such as password resets or verification emails.

The following sample demonstrates `{{correlation_id}}` added to an email template body.

```liquid wrap lines theme={null}
<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](/docs/customize/phone-messages/phone-templates) to trace authentication events that trigger SMS notifications, such as MFA challenges.

The following sample demonstrates `{{correlation_id}}` added to an SMS template.

```liquid wrap lines theme={null}
Your verification code is: {{code}}. Ref: {{correlation_id}}
```

## Custom Error Pages

You can include `correlation_id` in [Custom Error Pages](/docs/customize/login-pages/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.

The following sample demonstrates `{{correlation_id}}` added to a custom error page template.

```liquid wrap lines theme={null}
<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](/docs/customize/actions/explore-triggers/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`:

* [Pre-user-registration](/docs/customize/actions/explore-triggers/signup-and-login-triggers/pre-user-registration-trigger/pre-user-registration-event-object)
* [Post-login](/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object)
* [Post-challenge](/docs/customize/actions/explore-triggers/password-reset-triggers/post-challenge-trigger/post-challenge-event-object)
* [Post-change-password](/docs/customize/actions/explore-triggers/password-reset-triggers/post-change-password-trigger/post-change-password-event-object)
* [Custom email provider](/docs/customize/email/smtp-email-providers/custom/action-triggers-custom-email-provider-event-object)
* [Custom phone provider](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider/actions-triggers-custom-phone-provider-event-object)
* [MFA Notification send-phone-message](/docs/customize/actions/explore-triggers/mfa-notifications-trigger/send-phone-message-event-object)
* [Credential Exchange](/docs/customize/actions/explore-triggers/machine-to-machine-trigger/credentials-exchange-event-object)

The sample Post-Login Action demonstrates how to extract the `correlation_id` from the `event` object.

```javascript wrap lines theme={null}
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](/docs/customize/forms/variables).