Using npm in your project directory run the following command:
npm install auth0
[!NOTE]
Release channels. Endpoints move through three maturity tiers: Generally Available, Early Access, and Beta. This package is published on two channels. The stable channel (npm install auth0) includes the Generally Available and Early Access endpoints. The beta channel (npm install auth0@beta) is a superset that includes all three tiers.
Beta prereleases can introduce breaking changes between versions, so pin an exact version if you need reproducible installs.
Configure the SDK
Authentication
For authentication operations (OAuth flows, token management, user sign-up), use @auth0/auth0-auth-js. As of v7, node-auth0 no longer ships AuthenticationClient in its main entrypoint. The authentication layer has been separated into a dedicated package.
import { AuthClient } from "@auth0/auth0-auth-js";const auth = new AuthClient({ domain: "{YOUR_TENANT_AND REGION}.auth0.com", clientId: "{YOUR_CLIENT_ID}", clientSecret: "{OPTIONAL_CLIENT_SECRET}",});
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}",});
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});
If you only need a few Management API resources, you can import them individually instead of
the full ManagementClient. Each resource has its own entry point (for example
auth0/clients, auth0/users, auth0/connections), so a bundler ships only the resources
you use. This keeps bundles small on size-constrained runtimes such as Cloudflare Workers.
To avoid wiring up authentication for every client, use createManagementAuth from
auth0/management. It handles the token once (fetching and refreshing via client
credentials, or accepting a static token) and gives you an options object you spread into
any sub-client. The token is cached and shared, so you are not re-authenticating per client.
import { createManagementAuth } from "auth0/management";import { ClientsClient } from "auth0/clients";import { UsersClient } from "auth0/users";// Configure auth once and reuse it across clients.const auth = createManagementAuth({ domain: "{YOUR_TENANT_AND_REGION}.auth0.com", clientId: "{YOUR_CLIENT_ID}", clientSecret: "{YOUR_CLIENT_SECRET}",});// Create each sub-client once and reuse the instances throughout your app.export const clients = new ClientsClient(auth.clientOptions);export const users = new UsersClient(auth.clientOptions);await users.list({ page: 0, per_page: 10 });
For lower-level control over the token lifecycle, TokenProvider is also exported from
auth0/management. It performs the client credentials grant and caches the token until
shortly before it expires:
import { TokenProvider } from "auth0/management";import { ClientsClient } from "auth0/clients";const tokenProvider = new TokenProvider({ domain: "{YOUR_TENANT_AND_REGION}.auth0.com", clientId: "{YOUR_CLIENT_ID}", clientSecret: "{YOUR_CLIENT_SECRET}", audience: "https://{YOUR_TENANT_AND_REGION}.auth0.com/api/v2/",});const clients = new ClientsClient({ baseUrl: "https://{YOUR_TENANT_AND_REGION}.auth0.com/api/v2", token: () => tokenProvider.getAccessToken(),});
Request and response types for these clients live under the shared Management namespace and
are imported separately with import type { Management } from "auth0":
import type { Management } from "auth0";const body: Management.CreateClientRequestContent = { name: "My App" };const created: Management.CreateClientResponseContent = await clients.create(body);
Because they are TypeScript interfaces, import type is erased at compile time, so importing
types from the root auth0 entry adds nothing to your bundle and does not pull in the full
ManagementClient.
Recommendations for small bundles
Import each client as a value from its own entry point (auth0/clients, auth0/users,
and so on), not from the root auth0. A value import from the root pulls the full
ManagementClient and all resources into the module graph.
Import request and response types with import type { Management } from "auth0". Types are
erased, so this is always free regardless of the entry point.
Prefer import type over a plain import for anything you only use in type positions. It
guarantees the import is erased and never accidentally ships runtime code (the one thing
that does add bytes is referencing an enum value, such as OauthScope.CreateActions).
Configure authentication once with createManagementAuth (or a single shared
TokenProvider) and reuse the returned clientOptions across every sub-client. Create each
sub-client once and reuse the instance rather than constructing new clients per request.
These smaller bundles rely on tree-shaking, so they apply when you consume the SDK as ESM
through a bundler. A plain CommonJS require() cannot tree-shake and loads the full
resource graph.
User Profile Information
As of v7, node-auth0 no longer ships UserInfoClient. Use authClient.getUserInfo from @auth0/auth0-auth-js instead.
import { AuthClient } from "@auth0/auth0-auth-js";const auth = new AuthClient({ domain: "...", clientId: "..." });// Requires a default OIDC token (openid scope, no explicit audience).// If your app uses MRRT, request https://{domain}/userinfo as the audience.const profile = await auth.getUserInfo({ accessToken });
Note: tokens issued with a custom audience (e.g. the Management API) are rejected by /userinfo. Use a token obtained without an explicit audience, or request https://{domain}/userinfo as the audience when using MRRT.
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.
Note: The legacy entrypoint still includes AuthenticationClient from the v4.x API. This is separate from the v7 main entrypoint, which no longer ships authentication clients.
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 API:
Legacy Management Client
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);}
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:
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.
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!
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.