How to Disable Telemetry in Auth0 Auth JS Using AuthClientOptions

Set telemetry: { enabled: false } in your AuthClientOptions to prevent the SDK from sending the Auth0-Client header with every request.

The auth0-auth-js SDK automatically tracks anonymous usage data through a telemetry system that attaches an Auth0-Client header to every HTTP request. This header contains base-64-encoded metadata about the SDK version and package name, helping Auth0 diagnose integration issues and improve the product. If your organization prohibits client-side telemetry or you need to customize the identifying information, you can configure this behavior through the telemetry property in AuthClientOptions.

What Is Telemetry in Auth0 Auth JS?

Telemetry in the Auth0 Auth JS SDK refers to the automatic injection of an Auth0-Client HTTP header on every network request. The header value is a base-64-encoded JSON object containing the SDK's package name and version (for example, @auth0/auth0-auth-js and its current semver).

The primary purpose is to provide Auth0 with anonymous usage statistics—such as SDK version distribution and request volume—without requiring developers to implement additional logging or reporting code. This data helps Auth0 identify integration issues, prioritize bug fixes, and plan feature development.

The telemetry implementation lives in src/telemetry.ts, specifically within the createTelemetryFetch function, which generates the header and wraps the underlying fetch implementation.

How Telemetry Works Under the Hood

When you instantiate AuthClient, the constructor creates a custom fetch wrapper that conditionally injects the telemetry header. In src/auth-client.ts, the initialization logic looks like this:

// src/auth-client.ts
this.#customFetch = createTelemetryFetch(
  options.customFetch ?? ((...args) => fetch(...args)),
  getTelemetryConfig(options.telemetry)
);

The createTelemetryFetch function in src/telemetry.ts checks whether telemetry is enabled before wrapping the fetch call:

// src/telemetry.ts
if (config.enabled === false) {
  return baseFetch;  // Returns the original fetch without modification
}

If telemetry is enabled, the wrapper intercepts every request, constructs the Auth0-Client header by base-64-encoding the telemetry metadata, and appends it to the request headers before executing the network call.

Disabling Telemetry via AuthClientOptions

The AuthClientOptions interface exposes an optional telemetry property that accepts a TelemetryConfig object. This configuration determines whether the SDK injects the Auth0-Client header and what data it contains.

The TelemetryConfig Interface

As defined in the source types, TelemetryConfig supports two modes of operation:

1. Disable telemetry entirely by setting enabled: false
2. Customize the payload by providing name and version strings to override the default SDK metadata

Complete Disable Example

To completely disable telemetry and prevent the Auth0-Client header from being sent, pass telemetry: { enabled: false } in your client configuration:

import { AuthClient } from '@auth0/auth0-auth-js';

const auth = new AuthClient({
  domain: 'mytenant.auth0.com',
  clientId: 'YOUR_CLIENT_ID',
  telemetry: { enabled: false }  // Disables the Auth0-Client header
});

When this configuration is provided, getTelemetryConfig returns the object with enabled: false, causing createTelemetryFetch to return the unmodified fetch implementation and bypass all header injection logic.

Custom Telemetry Values

If you prefer to identify your application rather than disable telemetry entirely, you can override the default package metadata:

import { AuthClient } from '@auth0/auth0-auth-js';

const auth = new AuthClient({
  domain: 'mytenant.auth0.com',
  clientId: 'YOUR_CLIENT_ID',
  telemetry: {
    name: '@myorg/my-custom-app',
    version: '2.3.0'
  }
});

This configuration sends the Auth0-Client header with your specified name and version instead of the SDK's default values, allowing you to track usage specific to your application or wrapper library.

Summary

• Telemetry purpose: The Auth0 Auth JS SDK automatically sends an Auth0-Client header containing base-64-encoded package metadata to help Auth0 track SDK usage and diagnose issues.
• Implementation location: The telemetry wrapper is implemented in src/telemetry.ts via createTelemetryFetch and wired into the client in src/auth-client.ts.
• Disabling telemetry: Set telemetry: { enabled: false } in AuthClientOptions to prevent the SDK from injecting the Auth0-Client header on any request.
• Customization alternative: Instead of disabling, you can override the telemetry payload by providing custom name and version values to identify your application.

Frequently Asked Questions

What data does the Auth0 telemetry header contain?

The Auth0-Client header contains a base-64-encoded JSON object with the SDK's package name and version (for example, @auth0/auth0-auth-js and its semantic version). This data is anonymous and contains no user-identifiable information or authentication tokens.

Does disabling telemetry affect authentication functionality?

No. Disabling telemetry by setting telemetry: { enabled: false } only prevents the SDK from adding the Auth0-Client header to HTTP requests. All authentication flows, token requests, and API calls continue to function normally without this header.

Can I set custom telemetry values instead of disabling it?

Yes. Instead of disabling telemetry entirely, you can provide custom name and version strings in the telemetry configuration object. This overrides the default SDK metadata and sends your custom values in the Auth0-Client header, which is useful for tracking usage of wrapper libraries or specific application versions.

Where is the telemetry logic implemented in the SDK?

The telemetry implementation is located in src/telemetry.ts, specifically within the createTelemetryFetch function that wraps the fetch implementation. The configuration is wired into the AuthClient class in src/auth-client.ts, which passes the telemetry settings from AuthClientOptions to the fetch wrapper during initialization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}