A guide to migrating the Auth0 Node.js SDK from 6.x to 7.x.
Migrating with an AI agent? Point it at the Auth0 migration skill first. The skill lives in
auth0/agent-skillsas theauth0skill (migration intent:migrate-node-auth0). It encodes the authentication-layer rewrite rules and a verify loop.
V7 makes node-auth0 a Management-API-only SDK. The Authentication API layer (AuthenticationClient, its sub-clients, and UserInfoClient) has been removed from the main entrypoint. ManagementClient continues to work exactly as before; it now acquires its internal token directly via the client credentials grant rather than through the removed authentication layer.
If your code only uses ManagementClient, the upgrade is small: address the Management-side breaking changes below (mTLS, domain validation, error type) and you are done. If your code uses AuthenticationClient or UserInfoClient, that code must move to a dedicated package; see Migrating authentication code.
AuthenticationClient and UserInfoClient are no longer exported from the auth0 main entrypoint. The stateless authentication layer now lives in @auth0/auth0-auth-js, and the server-managed session layer lives in @auth0/auth0-server-js.
Before (v6):
import { AuthenticationClient, UserInfoClient } from "auth0";
const auth = new AuthenticationClient({ domain, clientId, clientSecret });
const tokens = await auth.oauth.clientCredentialsGrant({ audience });After (v7):
import { AuthClient } from "@auth0/auth0-auth-js";
const auth = new AuthClient({ domain, clientId, clientSecret });
const tokens = await auth.getTokenByClientCredentials({ audience });The complete method-by-method mapping, the four cross-cutting behavior changes (return shape, casing, token expiry, error model), and the session-app wiring are documented in the dedicated Authentication Migration Guide. This guide does not repeat that detail.
If you need the old clients unchanged as a stopgap, they still ship from the legacy entrypoint.
The following symbols were exported from the main entrypoint in v6 and are removed in v7. Each moves to @auth0/auth0-auth-js, or remains available from the auth0/legacy entrypoint at its v4.x shape.
| Removed export (v6) | Replacement in v7 |
|---|---|
AuthenticationClient |
AuthClient from @auth0/auth0-auth-js |
UserInfoClient |
AuthClient.getUserInfo() from @auth0/auth0-auth-js, or read TokenResponse.claims |
AuthApiError |
Per-operation typed errors from @auth0/auth0-auth-js (TokenByCodeError, TokenByRefreshTokenError, …); use their .cause |
AuthenticationClientOptions |
AuthClientOptions from @auth0/auth0-auth-js |
IDTokenValidateOptions |
Validation is internal to the grant call; pass organization / nonce / maxAge to the grant and read TokenResponse.claims |
IdTokenValidatorError |
Thrown internally by the grant as a typed error on claim mismatch |
TokenSet |
TokenResponse from @auth0/auth0-auth-js (camelCase fields; expiresAt is absolute) |
SUBJECT_TOKEN_TYPES |
Pass the token-type URN string directly to exchangeToken in @auth0/auth0-auth-js |
UserInfoResponse |
Return type of AuthClient.getUserInfo() in @auth0/auth0-auth-js |
UserInfoError |
Typed error from AuthClient.getUserInfo() in @auth0/auth0-auth-js |
ResponseError |
Management API calls throw ManagementError |
FetchError |
Management API calls throw ManagementError |
JSONApiResponse |
Responses return the data directly (no wrapper) |
ManagementClient, the Management namespace, and ManagementError are unchanged and still exported.
A ManagementClient constructed with useMTLS: true must now supply an explicit fetch option carrying the client certificate. The client throws at construction if useMTLS is set without a fetch. Previously a missing fetch surfaced as silent 401s at request time; failing at construction makes the misconfiguration obvious.
The token endpoint automatically uses the mtls.{domain} host when useMTLS is enabled.
// v7: throws at construction if `fetch` is omitted
const mgmt = new ManagementClient({
domain,
clientId,
clientSecret,
useMTLS: true,
fetch: mtlsCapableFetch, // now required
});useMTLS works with both clientSecret and clientAssertionSigningKey. mTLS (RFC 8705) is a transport-layer concern: the TLS client certificate yields a certificate-bound token regardless of which client authentication method is used. An explicit fetch option is always required when useMTLS is set.
domain must be a bare host such as tenant.us.auth0.com. A value that is empty, or that contains a scheme, a path, a query string, a fragment, credentials (@), or whitespace, now throws at construction instead of producing malformed request URLs later. The check applies to every authentication mode (token, clientSecret, and clientAssertionSigningKey), and to createManagementAuth and TokenProvider as well as ManagementClient.
// throws in v7
new ManagementClient({ domain: "https://tenant.us.auth0.com/", ... });
// correct
new ManagementClient({ domain: "tenant.us.auth0.com", ... });When the internal client-credentials token request fails, the client now throws a ManagementError (previously a plain Error). The error carries statusCode and a parsed body with the OAuth error details. A request that exceeds the 10-second timeout throws ManagementError with status 408.
import { ManagementError } from "auth0";
try {
await mgmt.users.getAll();
} catch (e) {
if (e instanceof ManagementError) {
console.error(e.statusCode, e.body);
}
}The uuid package is no longer a dependency. If your project imported uuid transitively through auth0, add it to your own dependencies.
If your app calls AuthenticationClient or UserInfoClient, follow the dedicated Authentication Migration Guide. Start with auth-migration/index.md for the OIDC token grants section; the incremental flow, session, and troubleshooting pages live in the same auth-migration/ directory. It covers:
- Choosing between
@auth0/auth0-auth-js(stateless token grants) and@auth0/auth0-server-js(server-managed sessions). - The complete method-by-method API mapping for
.oauth,.database,.passwordless,.backchannel,.tokenExchange, andUserInfoClient. - The four cross-cutting behavior changes: return shape (envelope dropped), casing (snake_case → camelCase), token expiry (
expires_inrelative →expiresAtabsolute, a silent high-risk change), and the typed error model withisMfaRequiredError(). - Wiring the
auth0-server-jssession lifecycle when you want the SDK to own login, cookies, refresh, and logout.
The Management API is explicitly out of scope in that guide: a file that keeps using ManagementClient from auth0 while importing @auth0/auth0-auth-js for authentication is correct and expected.
If you cannot migrate the authentication code immediately, the auth0/legacy entrypoint still ships AuthenticationClient and UserInfoClient at their v4.x configuration format and method signatures. This is a stopgap, not a destination; the legacy shapes differ from the current API and will not receive new features.
import { AuthenticationClient } from "auth0/legacy";Plan the move to @auth0/auth0-auth-js / @auth0/auth0-server-js rather than treating the legacy entrypoint as permanent.