5. Import from the root barrel:

import { AuthenticationClient, ManagementClient, UserInfoClient } from './src/vendor/auth0/index.js';

Public API

AuthenticationClient

class AuthenticationClient {
  database: Database;
  oauth: OAuth;
  passwordless: Passwordless;
  backchannel: IBackchannel;
  constructor(options: AuthenticationClientOptions): AuthenticationClient;
}

The primary entry point for all authentication flows. Instantiate once per application with your domain and client credentials. Use oauth for authorization code and client credentials flows, database for username/password signup and password change, passwordless for email/SMS OTP flows, and backchannel for CIBA.

ManagementClient

import { ManagementClient } from './src/vendor/auth0/index.js';
// Constructed with domain + token or client credentials:
const management = new ManagementClient({
  domain: string;
  token?: string;
  clientId?: string;
  clientSecret?: string;
});

The entry point for all Auth0 Management API operations. Provides access to users, clients, connections, organizations, logs, rules, and every other resource exposed by the Auth0 v2 Management API. Use this on trusted backend services only - never expose management credentials to clients.

ManagementClient (withCustomDomainHeader)

const management = new ManagementClient({
  domain: string;
  clientId: string;
  clientSecret: string;
  withCustomDomainHeader?: string; // e.g. 'auth.example.com'
});

Automatically applies the custom domain header to whitelisted Management API endpoints. Use this when your tenant uses a custom domain and you need API calls routed through it.

AuthApiError

import { AuthApiError } from './src/vendor/auth0/index.js';
// Thrown by AuthenticationClient methods on HTTP errors
class AuthApiError extends Error {
  statusCode: number;
  error: string;
  error_description: string;
}

Structured error thrown by all Authentication API methods. Catch it to distinguish auth errors (invalid credentials, expired tokens) from network failures.

ManagementError

import { ManagementError } from './src/vendor/auth0/index.js';
class ManagementError extends Error {
  statusCode: number;
}

Structured error thrown by Management API operations. Use statusCode to branch on 403 (forbidden), 404 (not found), 429 (rate limited), etc.

Working examples

Scenario - Exchange authorization code for tokens

A user completes the Auth0 Universal Login and your callback route receives a code. Exchange it for an access token and ID token.

import { AuthenticationClient, AuthApiError } from './src/vendor/auth0/index.js';

const auth0 = new AuthenticationClient({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
});

async function handleCallback(code: string, redirectUri: string) {
  try {
    const tokenSet = await auth0.oauth.authorizationCodeGrant({
      code,
      redirect_uri: redirectUri,
    });
    return tokenSet;
  } catch (err) {
    if (err instanceof AuthApiError) {
      console.error(`Auth error ${err.statusCode}: ${err.error_description}`);
    }
    throw err;
  }
}

Scenario - Create a new user via database connection

Register a new user against a Username-Password-Authentication connection.

import { AuthenticationClient } from './src/vendor/auth0/index.js';

const auth0 = new AuthenticationClient({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
});

async function registerUser(email: string, password: string) {
  const user = await auth0.database.signUp({
    connection: 'Username-Password-Authentication',
    email,
    password,
  });
  console.log('Created user:', user.data._id);
  return user;
}

Scenario - Fetch a user from the Management API

Retrieve a user record by ID on a backend admin route.

import { ManagementClient, ManagementError } from './src/vendor/auth0/index.js';

const management = new ManagementClient({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
});

async function getUser(userId: string) {
  try {
    const response = await management.users.get({ id: userId });
    return response.data;
  } catch (err) {
    if (err instanceof ManagementError && err.statusCode === 404) {
      return null;
    }
    throw err;
  }
}

Scenario - Get user profile from an access token

Retrieve the authenticated user's profile using a bearer access token.

import { UserInfoClient } from './src/vendor/auth0/index.js';

const userInfo = new UserInfoClient({
  domain: process.env.AUTH0_DOMAIN!,
});

async function getUserProfile(accessToken: string) {
  const profile = await userInfo.getUserInfo(accessToken);
  return profile.data;
}

File walkthrough

• index.ts - Root barrel; re-exports everything from management/, auth/, userinfo/, lib/errors, lib/models, and lib/httpResponseHeadersUtils.
• utils.ts - Internal utility functions shared across auth and management modules.
• auth/ - All Authentication API logic: OAuth flows, database connections, passwordless, CIBA, token exchange, ID token validation, and the AuthenticationClient class.
• auth/backchannel.ts - CIBA (Client-Initiated Backchannel Authentication) implementation.
• auth/base-auth-api.ts - Base class and AuthenticationClientOptions type used by all auth sub-clients.
• auth/client-authentication.ts - Client assertion and secret-based authentication helpers.
• auth/database.ts - Database class: signUp, changePassword.
• auth/id-token-validator.ts - ID token validation logic and IdTokenValidatorError.
• auth/oauth.ts - OAuth class: authorization code grant, client credentials, refresh token, device code, etc.
• auth/passwordless.ts - Passwordless class: send and verify email/SMS OTP.
• auth/tokenExchange.ts - CustomTokenExchange for custom token exchange flows.
• lib/ - Shared infrastructure: error base classes, HTTP header utilities, retry configuration, runtime detection.
• lib/errors.ts - Exported error types used across the SDK.
• lib/models.ts - Shared TypeScript model types.
• lib/retry.ts - RetryConfiguration type and retry logic.
• lib/middleware/auth0-client-telemetry.ts - Middleware that appends Auth0 client telemetry headers.
• management/ - Full Management API implementation: resource clients, request builders, error types, and the ManagementClient wrapper.
• management/Client.ts - Low-level HTTP client used by management resource classes.
• management/wrapper/ManagementClient.ts - High-level ManagementClient class exposing all resource namespaces.
• management/api/resources/ - One sub-directory per Management API resource (users, clients, connections, organizations, etc.).
• management/api/errors/ - Typed HTTP error classes (400, 401, 403, 404, 409, 429, 500, 503, etc.).
• management/request-options.ts - Helpers: withTimeout, withRetries, withHeaders, withAbortSignal, CustomDomainHeader.
• userinfo/ - UserInfoClient implementation for the /userinfo endpoint.

Common pitfalls and fixes

• ESM .js extension imports: The source uses import ... from './foo.js' even for .ts files. Set "moduleResolution": "NodeNext" in tsconfig.json; do not strip extensions.
• Node.js version: The SDK requires Node ^20.19.0 || ^22.12.0 || ^24.0.0. Running on Node 18 causes runtime failures; pin your engine in package.json.
• Missing jose or uuid: These are runtime dependencies not bundled. If you see Cannot find module 'jose', run npm install jose uuid.
• Management token vs. client credentials: Passing a raw token skips automatic token renewal; use clientId+clientSecret for long-running services so the SDK auto-refreshes.
• AUTH0_DOMAIN must not include https://: Pass only the bare domain string (your-tenant.auth0.com), not a full URL - the SDK constructs URLs internally.
• Rate limiting (429): The Management API enforces rate limits. Catch ManagementError with statusCode === 429 and implement exponential backoff using withRetries from management/request-options.ts.

Vibe-coding prompt template

I have dropped the Auth0 Node.js SDK source into `src/vendor/auth0/` in my project.
The integration guide is in `USAGE.md` next to this source directory.
The upstream package is `user@example.com`.

Please help me integrate this SDK into my project step by step:

1. Read `USAGE.md` for the required dependencies, tsconfig settings, and environment variables.
2. Install all required npm packages listed in USAGE.md.
3. Update my `tsconfig.json` to support NodeNext module resolution.
4. Create an `src/lib/auth0.ts` singleton that exports a configured `AuthenticationClient`
   and `ManagementClient` using environment variables for domain, clientId, and clientSecret.
   Import only from `src/vendor/auth0/index.js`.
5. Add an Express route `POST /auth/callback` that calls `auth0.oauth.authorizationCodeGrant`
   with the `code` and `redirect_uri` from the request body.
6. Add an Express route `GET /users/:id` that calls `management.users.get` and returns the user JSON.
7. Handle `AuthApiError` and `ManagementError` in each route, returning appropriate HTTP status codes.
8. Show me the complete file contents for each file you create or modify.

License and credit

The upstream package is licensed under the MIT License. See the auth0/node-auth0 repository for the full license text and source. Upstream npm package: user@example.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.