{"id":12852,"library":"auth0","title":"Auth0 Node.js SDK","description":"The `auth0` package is the official Node.js SDK for interacting with Auth0 services, providing robust clients for the Auth0 Management API v2, Authentication API, and UserInfo API. Currently at version 5.7.0, this library maintains an active development pace with frequent minor releases, often adding support for new Auth0 features and API endpoints. It is designed for server-side applications, offering strong TypeScript support and explicit compatibility with modern Node.js versions (specifically `^20.19.0 || ^22.12.0 || ^24.0.0`). A key differentiator is its clear separation between the current v5 API and a dedicated `/legacy` export path for maintaining compatibility with the v4.x API, facilitating smoother migrations while offering access to the latest features. It simplifies administrative tasks and user authentication flows in Node.js environments.","status":"active","version":"5.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/auth0/node-auth0","tags":["javascript","auth0","authentication","login","auth","jwt","management api","json web token","typescript"],"install":[{"cmd":"npm install auth0","lang":"bash","label":"npm"},{"cmd":"yarn add auth0","lang":"bash","label":"yarn"},{"cmd":"pnpm add auth0","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Used for interacting with the Auth0 Authentication API. The primary export is ESM-first; avoid CommonJS 'require' in modern Node.js projects.","wrong":"const { AuthenticationClient } = require('auth0');","symbol":"AuthenticationClient","correct":"import { AuthenticationClient } from 'auth0';"},{"note":"The main client for the Auth0 Management API v2, providing administrative capabilities. It is a named export, not a default export.","wrong":"import ManagementClient from 'auth0';","symbol":"ManagementClient","correct":"import { ManagementClient } from 'auth0';"},{"note":"Utilized for retrieving user profile information from an access token. As with other clients, prefer ESM imports.","wrong":"const UserInfoClient = require('auth0').UserInfoClient;","symbol":"UserInfoClient","correct":"import { UserInfoClient } from 'auth0';"},{"note":"For compatibility with `node-auth0` v4.x API. Use this specific import path if migrating or needing to maintain legacy code behavior.","wrong":"import { ManagementClient } from 'auth0';","symbol":"ManagementClient (Legacy)","correct":"import { ManagementClient } from 'auth0/legacy';"}],"quickstart":{"code":"import { ManagementClient } from 'auth0';\n\nasync function main() {\n  const domain = process.env.AUTH0_DOMAIN ?? 'your-tenant-and-region.auth0.com';\n  const clientId = process.env.AUTH0_CLIENT_ID ?? 'YOUR_CLIENT_ID';\n  const clientSecret = process.env.AUTH0_CLIENT_SECRET ?? 'YOUR_CLIENT_SECRET';\n\n  if (!process.env.AUTH0_DOMAIN || !process.env.AUTH0_CLIENT_ID || !process.env.AUTH0_CLIENT_SECRET) {\n    console.warn(\"Please set AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_CLIENT_SECRET environment variables for a real example.\");\n  }\n\n  const management = new ManagementClient({\n    domain,\n    clientId,\n    clientSecret\n  });\n\n  try {\n    console.log(\"Fetching up to 5 users...\");\n    const users = await management.users.getAll({ per_page: 5, page: 0 });\n    console.log(`Found ${users.length} users (showing first 5):`);\n    users.forEach(user => console.log(`- ${user.email || user.user_id}`));\n\n    console.log(\"\\nFetching client details for the provided client ID...\");\n    const client = await management.clients.get({ client_id: clientId });\n    console.log(`Client Name: ${client.name}`);\n    console.log(`Client ID: ${client.client_id}`);\n\n  } catch (error) {\n    console.error(\"An error occurred:\", error);\n    if (error instanceof Error) {\n        console.error(\"Error message:\", error.message);\n        // console.error(\"Stack trace:\", error.stack); // Uncomment for full stack trace\n    }\n    if (typeof error === 'object' && error !== null && 'statusCode' in error) {\n      console.error(`Status Code: ${error.statusCode}`);\n    }\n  }\n}\n\nmain();","lang":"typescript","description":"Initializes the Auth0 ManagementClient with client credentials from environment variables and fetches a list of users and specific client details from the Auth0 API."},"warnings":[{"fix":"Either refactor your code to use the new v5 API surface or import `ManagementClient` and `AuthenticationClient` from the dedicated `auth0/legacy` path to maintain v4.x compatibility.","message":"The transition from `node-auth0` v4.x to v5.x introduced significant API changes. Code written for v4.x will likely break without modification.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure your Node.js environment meets the minimum requirements. Upgrade Node.js to one of the supported versions if you encounter engine compatibility errors.","message":"This library has strict Node.js engine requirements, dropping support for older LTS versions. The package explicitly requires Node.js `^20.19.0 || ^22.12.0 || ^24.0.0`.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Prioritize initializing `ManagementClient` with `clientId` and `clientSecret` for server-side applications to leverage automatic token management and refresh capabilities, reducing the risk of expired tokens.","message":"When initializing the `ManagementClient`, it's generally more robust to use `clientId` and `clientSecret` for client credentials flow instead of directly providing a static `token`. Using client credentials allows the SDK to handle token issuance and refresh automatically.","severity":"gotcha","affected_versions":"*"},{"fix":"Implement robust error handling with retry logic and exponential backoff for API calls. Review Auth0's rate limit documentation and optimize your application's API usage patterns.","message":"Auth0's Management API has rate limits. Frequent or high-volume API calls without proper handling can lead to `429 Too Many Requests` errors.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Switch to ES Module `import { ManagementClient } from 'auth0';` syntax. If targeting the legacy v4 API, use `const { ManagementClient } = require('auth0/legacy');`.","cause":"Attempting to use CommonJS `require()` syntax with `auth0` package which is primarily an ESM module in modern Node.js environments.","error":"TypeError: Cannot destructure property 'ManagementClient' of 'require(...)' as it is undefined."},{"fix":"Configure your project to use ES Modules by adding `\"type\": \"module\"` to your `package.json` and updating your source files to use `import`/`export` syntax. Alternatively, ensure your Node.js version supports seamless ESM/CJS interop or check for a specific CommonJS entry point if available.","cause":"Your Node.js project is running in CommonJS mode (e.g., no `\"type\": \"module\"` in `package.json`), and you're trying to `require()` an ESM-only package.","error":"ERR_REQUIRE_ESM: require() of ES Module ...auth0/dist/index.js not supported."},{"fix":"Verify that your Auth0 application credentials (client ID, client secret) are correct. For `ManagementClient`, ensure your API token is valid, unexpired, and has all required Management API scopes configured (e.g., `read:users`, `update:users`). Generate a new token if necessary.","cause":"The Auth0 domain, client ID, client secret, or API token provided during client initialization is incorrect, expired, or lacks the necessary permissions (scopes) for the requested operation.","error":"Auth0Error: Unauthorized: Bad credentials (or Invalid Token / Missing scopes)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null}