📚 Documentation - 🚀 Getting Started - 💻 API Reference - 💬 Feedback

Documentation

• Docs Site - explore our docs site and learn more about Auth0
• SDK Documentation - explore the SDK documentation
• API Reference - full reference for this library
• v6 Migration Guide - upgrade from v5 to v6

Getting Started

Requirements

This library supports the following tooling versions:

• Node.js: ^20.19.0 || ^22.12.0 || ^24.0.0 || ^26.0.0

Installation

Using npm in your project directory run the following command:

npm install auth0

Configure the SDK

Authentication API Client

This client can be used to access Auth0's Authentication API.

import{AuthenticationClient}from"auth0";constauth0=newAuthenticationClient({domain: "{YOUR_TENANT_AND REGION}.auth0.com",clientId: "{YOUR_CLIENT_ID}",clientSecret: "{OPTIONAL_CLIENT_SECRET}",});

Management API Client

The Auth0 Management API is meant to be used by back-end servers or trusted parties performing administrative tasks. Generally speaking, anything that can be done through the Auth0 dashboard (and more) can also be done through this API.

Initialize your client class with a domain and token:

import{ManagementClient}from"auth0";constmanagement=newManagementClient({domain: "{YOUR_TENANT_AND REGION}.auth0.com",token: "{YOUR_API_V2_TOKEN}",});

Or use client credentials:

import{ManagementClient}from"auth0";constmanagement=newManagementClient({domain: "{YOUR_TENANT_AND REGION}.auth0.com",clientId: "{YOUR_CLIENT_ID}",clientSecret: "{YOUR_CLIENT_SECRET}",withCustomDomainHeader: "auth.example.com",// Optional: Auto-applies to whitelisted endpoints});

UserInfo API Client

This client can be used to retrieve user profile information.

import{UserInfoClient}from"auth0";constuserInfo=newUserInfoClient({domain: "{YOUR_TENANT_AND REGION}.auth0.com",});// Get user info with an access tokenconstuserProfile=awaituserInfo.getUserInfo(accessToken);

Legacy Usage

If you are migrating from the legacy node-auth0 package (v4.x) or need to maintain compatibility with legacy code, you can use the legacy export which provides the node-auth0 v4.x API interface.

Installing Legacy Version

The legacy version (node-auth0 v4.x) is available through the /legacy export path:

// Import the legacy version (node-auth0 v4.x API)import{ManagementClient,AuthenticationClient}from"auth0/legacy";// Or using CommonJSconst{ ManagementClient, AuthenticationClient }=require("auth0/legacy");

Legacy Configuration

The legacy API uses the node-auth0 v4.x configuration format and method signatures, which are different from the current v6 API:

Legacy Management Client

import{ManagementClient}from"auth0/legacy";constmanagement=newManagementClient({domain: "{YOUR_TENANT_AND REGION}.auth0.com",clientId: "{YOUR_CLIENT_ID}",clientSecret: "{YOUR_CLIENT_SECRET}",scope: "read:users update:users",});// Legacy API methods use promise-based patterns (node-auth0 v4.x style)management.users.getAll().then((users)=>console.log(users)).catch((err)=>console.error(err));// Or with async/awaittry{constusers=awaitmanagement.users.getAll();console.log(users);}catch(err){console.error(err);}

Legacy Authentication Client

import{AuthenticationClient}from"auth0/legacy";constauth0=newAuthenticationClient({domain: "{YOUR_TENANT_AND REGION}.auth0.com",clientId: "{YOUR_CLIENT_ID}",clientSecret: "{YOUR_CLIENT_SECRET}",});// Legacy authentication methods (node-auth0 v4.x style)auth0.oauth.passwordGrant({username: "user@example.com",password: "password",audience: "https://api.example.com",}).then((userData)=>{console.log(userData);}).catch((err)=>{console.error("Authentication error:",err);});// Or with async/awaittry{constuserData=awaitauth0.oauth.passwordGrant({username: "user@example.com",password: "password",audience: "https://api.example.com",});console.log(userData);}catch(err){console.error("Authentication error:",err);}

Migration from Legacy (node-auth0 v4) to v5

When migrating from node-auth0 v4.x to the current v5 SDK, note the following key differences:

1. Method Names: Many method names have changed to be more descriptive
2. Type Safety: Enhanced TypeScript support with better type definitions
3. Error Handling: Unified error handling with specific error types
4. Configuration: Simplified configuration options

Example Migration

Legacy (node-auth0 v4.x) code:

const{ ManagementClient }=require("auth0/legacy");constmanagement=newManagementClient({domain: "your-tenant.auth0.com",clientId: "YOUR_CLIENT_ID",clientSecret: "YOUR_CLIENT_SECRET",scope: "read:users",});// With promisesmanagement.users.getAll({search_engine: "v3"}).then((users)=>{console.log(users);}).catch((err)=>{console.error(err);});// Or with async/awaittry{constusers=awaitmanagement.users.getAll({search_engine: "v3"});console.log(users);}catch(err){console.error(err);}

v5 equivalent:

import{ManagementClient}from"auth0";constmanagement=newManagementClient({domain: "your-tenant.auth0.com",clientId: "YOUR_CLIENT_ID",clientSecret: "YOUR_CLIENT_SECRET",});// With promisesmanagement.users.list({searchEngine: "v3",}).then((users)=>{console.log(users);}).catch((error)=>{console.error(error);});// Or with async/awaittry{constusers=awaitmanagement.users.list({searchEngine: "v3",});console.log(users);}catch(error){console.error(error);}

Request and Response Types

The SDK exports all request and response types as TypeScript interfaces. You can import them directly:

import{ManagementClient,Management,ManagementError}from"auth0";constclient=newManagementClient({domain: "your-tenant.auth0.com",token: "YOUR_TOKEN",});// Use the request typeconstlistParams: Management.ListActionsRequestParameters={triggerId: "post-login",actionName: "my-action",};constactions=awaitclient.actions.list(listParams);

API Reference

Generated Documentation

• Full Reference - complete API reference guide

Key Classes

• ManagementClient - for Auth0 Management API operations
• AuthenticationClient - for Auth0 Authentication API operations
• UserInfoClient - for retrieving user profile information

Exception Handling

When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error will be thrown.

import{ManagementError}from"auth0";try{awaitclient.actions.create({name: "my-action",supported_triggers: [{id: "post-login"}],code: "exports.onExecutePostLogin = async (event, api) => { console.log('Hello World'); };",});}catch(err){if(errinstanceofManagementError){console.log(err.statusCode);console.log(err.message);console.log(err.body);console.log(err.rawResponse);}}

Pagination

Some list endpoints are paginated. You can iterate through pages using default values:

import{ManagementClient}from"auth0";constclient=newManagementClient({domain: "your-tenant.auth0.com",token: "YOUR_TOKEN",});// Using default pagination (page size defaults vary by endpoint)letpage=awaitclient.actions.list();for(constitemofpage.data){console.log(item);}while(page.hasNextPage()){page=awaitpage.getNextPage();for(constitemofpage.data){console.log(item);}}

Or you can explicitly control pagination using page and per_page parameters:

// Offset-based pagination (most endpoints)letpage=awaitclient.actions.list({page: 0,// Page number (0-indexed)per_page: 25,// Number of items per page});for(constitemofpage.data){console.log(item);}while(page.hasNextPage()){page=awaitpage.getNextPage();for(constitemofpage.data){console.log(item);}}

Some endpoints use checkpoint pagination with from and take parameters:

// Checkpoint-based pagination (e.g., connections, organizations)letpage=awaitclient.connections.list({take: 50,// Number of items per page});for(constitemofpage.data){console.log(item);}while(page.hasNextPage()){page=awaitpage.getNextPage();for(constitemofpage.data){console.log(item);}}

Advanced

Additional Headers

If you would like to send additional headers as part of the request, use the headers request option.

constresponse=awaitclient.actions.create({name: "my-action",supported_triggers: [{id: "post-login"}],},{headers: {"X-Custom-Header": "custom value",},},);

Request Helpers

The SDK provides convenient helper functions for common request configuration patterns:

import{ManagementClient,CustomDomainHeader,withTimeout,withRetries,withHeaders,withAbortSignal}from"auth0";constclient=newManagementClient({domain: "your-tenant.auth0.com",token: "YOUR_TOKEN",});// Example 1: Use custom domain header for specific requestsconstreqOptions={
...CustomDomainHeader("auth.example.com"),timeoutInSeconds: 30,};awaitclient.actions.list({},reqOptions);// Example 2: Combine multiple optionsconstreqOptions={
...withTimeout(30),
...withRetries(3),
...withHeaders({"X-Request-ID": crypto.randomUUID(),"X-Operation-Source": "admin-dashboard",}),};awaitclient.actions.list({},reqOptions);// Example 3: For automatic custom domain header on whitelisted endpointsconstclient=newManagementClient({domain: "your-tenant.auth0.com",token: "YOUR_TOKEN",withCustomDomainHeader: "auth.example.com",// Auto-applies to whitelisted endpoints});// Example 4: Request cancellationconstcontroller=newAbortController();constreqOptions={
...withAbortSignal(controller.signal),
...withTimeout(30),};constpromise=client.actions.list({},reqOptions);// Cancel after 10 secondssetTimeout(()=>controller.abort(),10000);

Available helper functions:

• CustomDomainHeader(domain) - Configure custom domain header for specific requests
• withTimeout(seconds) - Set request timeout
• withRetries(count) - Configure retry attempts
• withHeaders(headers) - Add custom headers
• withAbortSignal(signal) - Enable request cancellation

To apply the custom domain header globally across your application, use the withCustomDomainHeader option when initializing the ManagementClient. This will automatically inject the header for all whitelisted endpoints.

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retryable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the maxRetries request option to configure this behavior.

constresponse=awaitclient.actions.create({name: "my-action",supported_triggers: [{id: "post-login"}],},{maxRetries: 0,// override maxRetries at the request level},);

Timeouts

The SDK defaults to a 60 second timeout. Use the timeoutInSeconds option to configure this behavior.

constresponse=awaitclient.actions.create({name: "my-action",supported_triggers: [{id: "post-login"}],},{timeoutInSeconds: 30,// override timeout to 30s},);

Aborting Requests

The SDK allows users to abort requests at any point by passing in an abort signal.

constcontroller=newAbortController();constresponse=awaitclient.actions.create({name: "my-action",supported_triggers: [{id: "post-login"}],},{abortSignal: controller.signal,},);controller.abort();// aborts the request

Logging

The SDK supports configurable logging for debugging API requests and responses. By default, logging is silent.

import{ManagementClient}from"auth0";constclient=newManagementClient({domain: "your-tenant.auth0.com",clientId: "YOUR_CLIENT_ID",clientSecret: "YOUR_CLIENT_SECRET",logging: {level: "debug",// "debug" | "info" | "warn" | "error"silent: false,// Set to false to enable logging output},});

You can also provide a custom logger implementation:

import{ManagementClient}from"auth0";constcustomLogger={debug: (msg, ...args)=>myLogger.debug(msg,args),info: (msg, ...args)=>myLogger.info(msg,args),warn: (msg, ...args)=>myLogger.warn(msg,args),error: (msg, ...args)=>myLogger.error(msg,args),};constclient=newManagementClient({domain: "your-tenant.auth0.com",clientId: "YOUR_CLIENT_ID",clientSecret: "YOUR_CLIENT_SECRET",logging: {level: "info",logger: customLogger,silent: false,},});

Access Raw Response Data

The SDK provides access to raw response data, including headers, through the .withRawResponse() method. The .withRawResponse() method returns a promise that results to an object with a data and a rawResponse property.

const{ data, rawResponse }=awaitclient.actions.create({name: "my-action",supported_triggers: [{id: "post-login"}],}).withRawResponse();console.log(data);console.log(rawResponse.headers);

Runtime Compatibility

The SDK defaults to node-fetch but will use the global fetch client if present. The SDK works in the following runtimes:

• Node.js 20.19.0+, 22.12.0+, 24+, 26+
• Vercel
• Cloudflare Workers
• Deno v1.25+
• Bun 1.0+
• React Native

Feedback

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!

Raise an issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

What is Auth0?

Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0?

This project is licensed under the MIT license. See the LICENSE file for more info.