docs/index.html
š Documentation - š Getting Started - š» API Reference - š¬ Feedback
This library supports the following tooling versions:
^20.19.0 || ^22.12.0 || ^24.0.0Using npm in your project directory run the following command:
npm install auth0Copy
This client can be used to access Auth0's Authentication API.
import { AuthenticationClient } from "auth0";const auth0 = new AuthenticationClient({ domain: "{YOUR_TENANT_AND REGION}.auth0.com", clientId: "{YOUR_CLIENT_ID}", clientSecret: "{OPTIONAL_CLIENT_SECRET}",});Copy
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";const management = new ManagementClient({ domain: "{YOUR_TENANT_AND REGION}.auth0.com", token: "{YOUR_API_V2_TOKEN}",});Copy
Or use client credentials:
import { ManagementClient } from "auth0";const management = new ManagementClient({ 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});Copy
This client can be used to retrieve user profile information.
import { UserInfoClient } from "auth0";const userInfo = new UserInfoClient({ domain: "{YOUR_TENANT_AND REGION}.auth0.com",});// Get user info with an access tokenconst userProfile = await userInfo.getUserInfo(accessToken);Copy
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.
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");Copy
The legacy API uses the node-auth0 v4.x configuration format and method signatures, which are different from the current v5 API:
import { ManagementClient } from "auth0/legacy";const management = new ManagementClient({ 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 { const users = await management.users.getAll(); console.log(users);} catch (err) { console.error(err);}Copy
import { AuthenticationClient } from "auth0/legacy";const auth0 = new AuthenticationClient({ 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: "[email protected]", password: "password", audience: "https://api.example.com", }) .then((userData) => { console.log(userData); }) .catch((err) => { console.error("Authentication error:", err); });// Or with async/awaittry { const userData = await auth0.oauth.passwordGrant({ username: "[email protected]", password: "password", audience: "https://api.example.com", }); console.log(userData);} catch (err) { console.error("Authentication error:", err);}Copy
When migrating from node-auth0 v4.x to the current v5 SDK, note the following key differences:
Legacy (node-auth0 v4.x) code:
const { ManagementClient } = require("auth0/legacy");const management = new ManagementClient({ 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 { const users = await management.users.getAll({ search_engine: "v3" }); console.log(users);} catch (err) { console.error(err);}Copy
v5 equivalent:
import { ManagementClient } from "auth0";const management = new ManagementClient({ 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 { const users = await management.users.list({ searchEngine: "v3", }); console.log(users);} catch (error) { console.error(error);}Copy
The SDK exports all request and response types as TypeScript interfaces. You can import them directly:
import { ManagementClient, Management, ManagementError } from "auth0";const client = new ManagementClient({ domain: "your-tenant.auth0.com", token: "YOUR_TOKEN",});// Use the request typeconst listParams: Management.ListActionsRequestParameters = { triggerId: "post-login", actionName: "my-action",};const actions = await client.actions.list(listParams);Copy
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 { await client.actions.create({ name: "my-action", supported_triggers: [{ id: "post-login" }], code: "exports.onExecutePostLogin = async (event, api) => { console.log('Hello World'); };", });} catch (err) { if (err instanceof ManagementError) { console.log(err.statusCode); console.log(err.message); console.log(err.body); console.log(err.rawResponse); }}Copy
Some list endpoints are paginated. You can iterate through pages using default values:
import { ManagementClient } from "auth0";const client = new ManagementClient({ domain: "your-tenant.auth0.com", token: "YOUR_TOKEN",});// Using default pagination (page size defaults vary by endpoint)let page = await client.actions.list();for (const item of page.data) { console.log(item);}while (page.hasNextPage()) { page = await page.getNextPage(); for (const item of page.data) { console.log(item); }}Copy
Or you can explicitly control pagination using page and per_page parameters:
// Offset-based pagination (most endpoints)let page = await client.actions.list({ page: 0, // Page number (0-indexed) per_page: 25, // Number of items per page});for (const item of page.data) { console.log(item);}while (page.hasNextPage()) { page = await page.getNextPage(); for (const item of page.data) { console.log(item); }}Copy
Some endpoints use checkpoint pagination with from and take parameters:
// Checkpoint-based pagination (e.g., connections, organizations)let page = await client.connections.list({ take: 50, // Number of items per page});for (const item of page.data) { console.log(item);}while (page.hasNextPage()) { page = await page.getNextPage(); for (const item of page.data) { console.log(item); }}Copy
If you would like to send additional headers as part of the request, use the headers request option.
const response = await client.actions.create( { name: "my-action", supported_triggers: [{ id: "post-login" }], }, { headers: { "X-Custom-Header": "custom value", }, },);Copy
The SDK provides convenient helper functions for common request configuration patterns:
import { ManagementClient, CustomDomainHeader, withTimeout, withRetries, withHeaders, withAbortSignal } from "auth0";const client = new ManagementClient({ domain: "your-tenant.auth0.com", token: "YOUR_TOKEN",});// Example 1: Use custom domain header for specific requestsconst reqOptions = { ...CustomDomainHeader("auth.example.com"), timeoutInSeconds: 30,};await client.actions.list({}, reqOptions);// Example 2: Combine multiple optionsconst reqOptions = { ...withTimeout(30), ...withRetries(3), ...withHeaders({ "X-Request-ID": crypto.randomUUID(), "X-Operation-Source": "admin-dashboard", }),};await client.actions.list({}, reqOptions);// Example 3: For automatic custom domain header on whitelisted endpointsconst client = new ManagementClient({ domain: "your-tenant.auth0.com", token: "YOUR_TOKEN", withCustomDomainHeader: "auth.example.com", // Auto-applies to whitelisted endpoints});// Example 4: Request cancellationconst controller = new AbortController();const reqOptions = { ...withAbortSignal(controller.signal), ...withTimeout(30),};const promise = client.actions.list({}, reqOptions);// Cancel after 10 secondssetTimeout(() => controller.abort(), 10000);Copy
Available helper functions:
CustomDomainHeader(domain) - Configure custom domain header for specific requestswithTimeout(seconds) - Set request timeoutwithRetries(count) - Configure retry attemptswithHeaders(headers) - Add custom headerswithAbortSignal(signal) - Enable request cancellationTo 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.
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:
Use the maxRetries request option to configure this behavior.
const response = await client.actions.create( { name: "my-action", supported_triggers: [{ id: "post-login" }], }, { maxRetries: 0, // override maxRetries at the request level },);Copy
The SDK defaults to a 60 second timeout. Use the timeoutInSeconds option to configure this behavior.
const response = await client.actions.create( { name: "my-action", supported_triggers: [{ id: "post-login" }], }, { timeoutInSeconds: 30, // override timeout to 30s },);Copy
The SDK allows users to abort requests at any point by passing in an abort signal.
const controller = new AbortController();const response = await client.actions.create( { name: "my-action", supported_triggers: [{ id: "post-login" }], }, { abortSignal: controller.signal, },);controller.abort(); // aborts the requestCopy
The SDK supports configurable logging for debugging API requests and responses. By default, logging is silent.
import { ManagementClient } from "auth0";const client = new ManagementClient({ 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 },});Copy
You can also provide a custom logger implementation:
import { ManagementClient } from "auth0";const customLogger = { 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),};const client = new ManagementClient({ domain: "your-tenant.auth0.com", clientId: "YOUR_CLIENT_ID", clientSecret: "YOUR_CLIENT_SECRET", logging: { level: "info", logger: customLogger, silent: false, },});Copy
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 } = await client.actions .create({ name: "my-action", supported_triggers: [{ id: "post-login" }], }) .withRawResponse();console.log(data);console.log(rawResponse.headers);Copy
The SDK defaults to node-fetch but will use the global fetch client if present. The SDK works in the following runtimes:
We appreciate feedback and contribution to this repo! Before you get started, please see the following:
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!
To provide feedback or report a bug, please raise an issue on our issue tracker.
Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
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.
Member Visibility
ThemeOSLightDark
Request and Response TypesAPI Reference