{"id":13686105,"url":"https://github.com/auth0/node-auth0","last_synced_at":"2026-04-09T17:19:38.216Z","repository":{"id":5775939,"uuid":"6989650","full_name":"auth0/node-auth0","owner":"auth0","description":"Node.js client library for the Auth0 platform.","archived":false,"fork":false,"pushed_at":"2025-05-06T04:38:38.000Z","size":47791,"stargazers_count":657,"open_issues_count":31,"forks_count":312,"subscribers_count":79,"default_branch":"master","last_synced_at":"2025-05-06T05:29:57.474Z","etag":null,"topics":["dx-sdk"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/auth0.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-12-03T21:19:57.000Z","updated_at":"2025-05-06T04:38:43.000Z","dependencies_parsed_at":"2024-02-09T12:30:09.977Z","dependency_job_id":"fa6ca20c-8471-46a8-afd1-2518443147f1","html_url":"https://github.com/auth0/node-auth0","commit_stats":{"total_commits":1142,"total_committers":170,"mean_commits":"6.7176470588235295","dds":0.8931698774080561,"last_synced_commit":"34497ef7d95b5e2a4fe1f464df572f140b922599"},"previous_names":[],"tags_count":149,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0%2Fnode-auth0","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0%2Fnode-auth0/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0%2Fnode-auth0/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auth0%2Fnode-auth0/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/auth0","download_url":"https://codeload.github.com/auth0/node-auth0/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010797,"owners_count":21998993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dx-sdk"],"created_at":"2024-08-02T14:01:06.539Z","updated_at":"2026-01-29T09:17:17.034Z","avatar_url":"https://github.com/auth0.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Developer Ecosystem"],"sub_categories":[],"readme":"![Node.js client library for Auth0](https://cdn.auth0.com/website/sdks/banner/node-auth0-banner.png)\n\n![Release](https://img.shields.io/npm/v/auth0)\n[![Codecov](https://img.shields.io/codecov/c/github/auth0/node-auth0)](https://codecov.io/gh/auth0/node-auth0)\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/auth0/node-auth0)\n![Downloads](https://img.shields.io/npm/dw/auth0)\n[![License](https://img.shields.io/:license-mit-blue.svg?style=flat)](https://opensource.org/licenses/MIT)\n[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\u0026utm_medium=github\u0026utm_campaign=readme\u0026utm_source=https%3A%2F%2Fgithub.com%2Fauth0%2Fnode-auth0)\n\n📚 [Documentation](#documentation) - 🚀 [Getting Started](#getting-started) - 💻 [API Reference](#api-reference) - 💬 [Feedback](#feedback)\n\n## Documentation\n\n- [Docs Site](https://auth0.com/docs) - explore our docs site and learn more about Auth0\n- [SDK Documentation](http://auth0.github.io/node-auth0/) - explore the SDK documentation\n- [API Reference](https://github.com/auth0/node-auth0/blob/master/reference.md) - full reference for this library\n\n## Getting Started\n\n### Requirements\n\nThis library supports the following tooling versions:\n\n- Node.js: `^20.19.0 || ^22.12.0 || ^24.0.0`\n\n### Installation\n\nUsing [npm](https://npmjs.org) in your project directory run the following command:\n\n```bash\nnpm install auth0\n```\n\n### Configure the SDK\n\n#### Authentication API Client\n\nThis client can be used to access Auth0's [Authentication API](https://auth0.com/docs/api/authentication).\n\n```js\nimport { AuthenticationClient } from \"auth0\";\n\nconst auth0 = new AuthenticationClient({\n    domain: \"{YOUR_TENANT_AND REGION}.auth0.com\",\n    clientId: \"{YOUR_CLIENT_ID}\",\n    clientSecret: \"{OPTIONAL_CLIENT_SECRET}\",\n});\n```\n\n#### Management API Client\n\nThe 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.\n\nInitialize your client class with a domain and token:\n\n```js\nimport { ManagementClient } from \"auth0\";\n\nconst management = new ManagementClient({\n    domain: \"{YOUR_TENANT_AND REGION}.auth0.com\",\n    token: \"{YOUR_API_V2_TOKEN}\",\n});\n```\n\nOr use client credentials:\n\n```js\nimport { ManagementClient } from \"auth0\";\n\nconst management = new ManagementClient({\n    domain: \"{YOUR_TENANT_AND REGION}.auth0.com\",\n    clientId: \"{YOUR_CLIENT_ID}\",\n    clientSecret: \"{YOUR_CLIENT_SECRET}\",\n    withCustomDomainHeader: \"auth.example.com\", // Optional: Auto-applies to whitelisted endpoints\n});\n```\n\n#### UserInfo API Client\n\nThis client can be used to retrieve user profile information.\n\n```js\nimport { UserInfoClient } from \"auth0\";\n\nconst userInfo = new UserInfoClient({\n    domain: \"{YOUR_TENANT_AND REGION}.auth0.com\",\n});\n\n// Get user info with an access token\nconst userProfile = await userInfo.getUserInfo(accessToken);\n```\n\n## Legacy Usage\n\nIf 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.\n\n### Installing Legacy Version\n\nThe legacy version (`node-auth0` v4.x) is available through the `/legacy` export path:\n\n```js\n// Import the legacy version (node-auth0 v4.x API)\nimport { ManagementClient, AuthenticationClient } from \"auth0/legacy\";\n\n// Or using CommonJS\nconst { ManagementClient, AuthenticationClient } = require(\"auth0/legacy\");\n```\n\n### Legacy Configuration\n\nThe legacy API uses the `node-auth0` v4.x configuration format and method signatures, which are different from the current v5 API:\n\n#### Legacy Management Client\n\n```js\nimport { ManagementClient } from \"auth0/legacy\";\n\nconst management = new ManagementClient({\n    domain: \"{YOUR_TENANT_AND REGION}.auth0.com\",\n    clientId: \"{YOUR_CLIENT_ID}\",\n    clientSecret: \"{YOUR_CLIENT_SECRET}\",\n    scope: \"read:users update:users\",\n});\n\n// Legacy API methods use promise-based patterns (node-auth0 v4.x style)\nmanagement.users\n    .getAll()\n    .then((users) =\u003e console.log(users))\n    .catch((err) =\u003e console.error(err));\n\n// Or with async/await\ntry {\n    const users = await management.users.getAll();\n    console.log(users);\n} catch (err) {\n    console.error(err);\n}\n```\n\n#### Legacy Authentication Client\n\n```js\nimport { AuthenticationClient } from \"auth0/legacy\";\n\nconst auth0 = new AuthenticationClient({\n    domain: \"{YOUR_TENANT_AND REGION}.auth0.com\",\n    clientId: \"{YOUR_CLIENT_ID}\",\n    clientSecret: \"{YOUR_CLIENT_SECRET}\",\n});\n\n// Legacy authentication methods (node-auth0 v4.x style)\nauth0.oauth\n    .passwordGrant({\n        username: \"user@example.com\",\n        password: \"password\",\n        audience: \"https://api.example.com\",\n    })\n    .then((userData) =\u003e {\n        console.log(userData);\n    })\n    .catch((err) =\u003e {\n        console.error(\"Authentication error:\", err);\n    });\n\n// Or with async/await\ntry {\n    const userData = await auth0.oauth.passwordGrant({\n        username: \"user@example.com\",\n        password: \"password\",\n        audience: \"https://api.example.com\",\n    });\n    console.log(userData);\n} catch (err) {\n    console.error(\"Authentication error:\", err);\n}\n```\n\n### Migration from Legacy (node-auth0 v4) to v5\n\nWhen migrating from `node-auth0` v4.x to the current v5 SDK, note the following key differences:\n\n1. **Method Names**: Many method names have changed to be more descriptive\n2. **Type Safety**: Enhanced TypeScript support with better type definitions\n3. **Error Handling**: Unified error handling with specific error types\n4. **Configuration**: Simplified configuration options\n\n#### Example Migration\n\n**Legacy (node-auth0 v4.x) code:**\n\n```js\nconst { ManagementClient } = require(\"auth0/legacy\");\n\nconst management = new ManagementClient({\n    domain: \"your-tenant.auth0.com\",\n    clientId: \"YOUR_CLIENT_ID\",\n    clientSecret: \"YOUR_CLIENT_SECRET\",\n    scope: \"read:users\",\n});\n\n// With promises\nmanagement.users\n    .getAll({ search_engine: \"v3\" })\n    .then((users) =\u003e {\n        console.log(users);\n    })\n    .catch((err) =\u003e {\n        console.error(err);\n    });\n\n// Or with async/await\ntry {\n    const users = await management.users.getAll({ search_engine: \"v3\" });\n    console.log(users);\n} catch (err) {\n    console.error(err);\n}\n```\n\n**v5 equivalent:**\n\n```js\nimport { ManagementClient } from \"auth0\";\n\nconst management = new ManagementClient({\n    domain: \"your-tenant.auth0.com\",\n    clientId: \"YOUR_CLIENT_ID\",\n    clientSecret: \"YOUR_CLIENT_SECRET\",\n});\n\n// With promises\nmanagement.users\n    .list({\n        searchEngine: \"v3\",\n    })\n    .then((users) =\u003e {\n        console.log(users);\n    })\n    .catch((error) =\u003e {\n        console.error(error);\n    });\n\n// Or with async/await\ntry {\n    const users = await management.users.list({\n        searchEngine: \"v3\",\n    });\n    console.log(users);\n} catch (error) {\n    console.error(error);\n}\n```\n\n## Request and Response Types\n\nThe SDK exports all request and response types as TypeScript interfaces. You can import them directly:\n\n```typescript\nimport { ManagementClient, Management, ManagementError } from \"auth0\";\n\nconst client = new ManagementClient({\n    domain: \"your-tenant.auth0.com\",\n    token: \"YOUR_TOKEN\",\n});\n\n// Use the request type\nconst listParams: Management.ListActionsRequestParameters = {\n    triggerId: \"post-login\",\n    actionName: \"my-action\",\n};\n\nconst actions = await client.actions.list(listParams);\n```\n\n## API Reference\n\n### Generated Documentation\n\n- [Full Reference](./reference.md) - complete API reference guide\n\n### Key Classes\n\n- **ManagementClient** - for Auth0 Management API operations\n- **AuthenticationClient** - for Auth0 Authentication API operations\n- **UserInfoClient** - for retrieving user profile information\n\n## Exception Handling\n\nWhen the API returns a non-success status code (4xx or 5xx response), a subclass of the following error\nwill be thrown.\n\n```typescript\nimport { ManagementError } from \"auth0\";\n\ntry {\n    await client.actions.create({\n        name: \"my-action\",\n        supported_triggers: [{ id: \"post-login\" }],\n        code: \"exports.onExecutePostLogin = async (event, api) =\u003e { console.log('Hello World'); };\",\n    });\n} catch (err) {\n    if (err instanceof ManagementError) {\n        console.log(err.statusCode);\n        console.log(err.message);\n        console.log(err.body);\n        console.log(err.rawResponse);\n    }\n}\n```\n\n## Pagination\n\nSome list endpoints are paginated. You can iterate through pages using default values:\n\n```typescript\nimport { ManagementClient } from \"auth0\";\n\nconst client = new ManagementClient({\n    domain: \"your-tenant.auth0.com\",\n    token: \"YOUR_TOKEN\",\n});\n\n// Using default pagination (page size defaults vary by endpoint)\nlet page = await client.actions.list();\nfor (const item of page.data) {\n    console.log(item);\n}\n\nwhile (page.hasNextPage()) {\n    page = await page.getNextPage();\n    for (const item of page.data) {\n        console.log(item);\n    }\n}\n```\n\nOr you can explicitly control pagination using `page` and `per_page` parameters:\n\n```typescript\n// Offset-based pagination (most endpoints)\nlet page = await client.actions.list({\n    page: 0, // Page number (0-indexed)\n    per_page: 25, // Number of items per page\n});\n\nfor (const item of page.data) {\n    console.log(item);\n}\n\nwhile (page.hasNextPage()) {\n    page = await page.getNextPage();\n    for (const item of page.data) {\n        console.log(item);\n    }\n}\n```\n\nSome endpoints use checkpoint pagination with `from` and `take` parameters:\n\n```typescript\n// Checkpoint-based pagination (e.g., connections, organizations)\nlet page = await client.connections.list({\n    take: 50, // Number of items per page\n});\n\nfor (const item of page.data) {\n    console.log(item);\n}\n\nwhile (page.hasNextPage()) {\n    page = await page.getNextPage();\n    for (const item of page.data) {\n        console.log(item);\n    }\n}\n```\n\n## Advanced\n\n### Additional Headers\n\nIf you would like to send additional headers as part of the request, use the `headers` request option.\n\n```typescript\nconst response = await client.actions.create(\n    {\n        name: \"my-action\",\n        supported_triggers: [{ id: \"post-login\" }],\n    },\n    {\n        headers: {\n            \"X-Custom-Header\": \"custom value\",\n        },\n    },\n);\n```\n\n### Request Helpers\n\nThe SDK provides convenient helper functions for common request configuration patterns:\n\n```typescript\nimport { ManagementClient, CustomDomainHeader, withTimeout, withRetries, withHeaders, withAbortSignal } from \"auth0\";\n\nconst client = new ManagementClient({\n    domain: \"your-tenant.auth0.com\",\n    token: \"YOUR_TOKEN\",\n});\n\n// Example 1: Use custom domain header for specific requests\nconst reqOptions = {\n    ...CustomDomainHeader(\"auth.example.com\"),\n    timeoutInSeconds: 30,\n};\nawait client.actions.list({}, reqOptions);\n\n// Example 2: Combine multiple options\nconst reqOptions = {\n    ...withTimeout(30),\n    ...withRetries(3),\n    ...withHeaders({\n        \"X-Request-ID\": crypto.randomUUID(),\n        \"X-Operation-Source\": \"admin-dashboard\",\n    }),\n};\nawait client.actions.list({}, reqOptions);\n\n// Example 3: For automatic custom domain header on whitelisted endpoints\nconst client = new ManagementClient({\n    domain: \"your-tenant.auth0.com\",\n    token: \"YOUR_TOKEN\",\n    withCustomDomainHeader: \"auth.example.com\", // Auto-applies to whitelisted endpoints\n});\n\n// Example 4: Request cancellation\nconst controller = new AbortController();\nconst reqOptions = {\n    ...withAbortSignal(controller.signal),\n    ...withTimeout(30),\n};\nconst promise = client.actions.list({}, reqOptions);\n\n// Cancel after 10 seconds\nsetTimeout(() =\u003e controller.abort(), 10000);\n```\n\nAvailable helper functions:\n\n- `CustomDomainHeader(domain)` - Configure custom domain header for specific requests\n- `withTimeout(seconds)` - Set request timeout\n- `withRetries(count)` - Configure retry attempts\n- `withHeaders(headers)` - Add custom headers\n- `withAbortSignal(signal)` - Enable request cancellation\n\nTo 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.\n\n### Retries\n\nThe SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long\nas the request is deemed retryable and the number of retry attempts has not grown larger than the configured\nretry limit (default: 2).\n\nA request is deemed retryable when any of the following HTTP status codes is returned:\n\n- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)\n- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)\n- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)\n\nUse the `maxRetries` request option to configure this behavior.\n\n```typescript\nconst response = await client.actions.create(\n    {\n        name: \"my-action\",\n        supported_triggers: [{ id: \"post-login\" }],\n    },\n    {\n        maxRetries: 0, // override maxRetries at the request level\n    },\n);\n```\n\n### Timeouts\n\nThe SDK defaults to a 60 second timeout. Use the `timeoutInSeconds` option to configure this behavior.\n\n```typescript\nconst response = await client.actions.create(\n    {\n        name: \"my-action\",\n        supported_triggers: [{ id: \"post-login\" }],\n    },\n    {\n        timeoutInSeconds: 30, // override timeout to 30s\n    },\n);\n```\n\n### Aborting Requests\n\nThe SDK allows users to abort requests at any point by passing in an abort signal.\n\n```typescript\nconst controller = new AbortController();\nconst response = await client.actions.create(\n    {\n        name: \"my-action\",\n        supported_triggers: [{ id: \"post-login\" }],\n    },\n    {\n        abortSignal: controller.signal,\n    },\n);\ncontroller.abort(); // aborts the request\n```\n\n### Logging\n\nThe SDK supports configurable logging for debugging API requests and responses. By default, logging is silent.\n\n```typescript\nimport { ManagementClient } from \"auth0\";\n\nconst client = new ManagementClient({\n    domain: \"your-tenant.auth0.com\",\n    clientId: \"YOUR_CLIENT_ID\",\n    clientSecret: \"YOUR_CLIENT_SECRET\",\n    logging: {\n        level: \"debug\", // \"debug\" | \"info\" | \"warn\" | \"error\"\n        silent: false, // Set to false to enable logging output\n    },\n});\n```\n\nYou can also provide a custom logger implementation:\n\n```typescript\nimport { ManagementClient } from \"auth0\";\n\nconst customLogger = {\n    debug: (msg, ...args) =\u003e myLogger.debug(msg, args),\n    info: (msg, ...args) =\u003e myLogger.info(msg, args),\n    warn: (msg, ...args) =\u003e myLogger.warn(msg, args),\n    error: (msg, ...args) =\u003e myLogger.error(msg, args),\n};\n\nconst client = new ManagementClient({\n    domain: \"your-tenant.auth0.com\",\n    clientId: \"YOUR_CLIENT_ID\",\n    clientSecret: \"YOUR_CLIENT_SECRET\",\n    logging: {\n        level: \"info\",\n        logger: customLogger,\n        silent: false,\n    },\n});\n```\n\n### Access Raw Response Data\n\nThe SDK provides access to raw response data, including headers, through the `.withRawResponse()` method.\nThe `.withRawResponse()` method returns a promise that results to an object with a `data` and a `rawResponse` property.\n\n```typescript\nconst { data, rawResponse } = await client.actions\n    .create({\n        name: \"my-action\",\n        supported_triggers: [{ id: \"post-login\" }],\n    })\n    .withRawResponse();\n\nconsole.log(data);\nconsole.log(rawResponse.headers);\n```\n\n### Runtime Compatibility\n\nThe SDK defaults to `node-fetch` but will use the global fetch client if present. The SDK works in the following\nruntimes:\n\n- Node.js 20.19.0+, 22.12.0+, 24+\n- Vercel\n- Cloudflare Workers\n- Deno v1.25+\n- Bun 1.0+\n- React Native\n\n## Feedback\n\n### Contributing\n\nWe appreciate feedback and contribution to this repo! Before you get started, please see the following:\n\n- [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)\n- [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)\n\nWhile we value open-source contributions to this SDK, this library is generated programmatically.\nAdditions made directly to this library would have to be moved over to our generation code,\notherwise they would be overwritten upon the next generated release. Feel free to open a PR as\na proof of concept, but know that we will not be able to merge it as-is. We suggest opening\nan issue first to discuss with us!\n\nOn the other hand, contributions to the README are always very welcome!\n\n### Raise an issue\n\nTo provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/node-auth0/issues).\n\n### Vulnerability Reporting\n\nPlease do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.\n\n## What is Auth0?\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.auth0.com/website/sdks/logos/auth0_dark_mode.png\" width=\"150\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png\" width=\"150\"\u003e\n    \u003cimg alt=\"Auth0 Logo\" src=\"https://cdn.auth0.com/website/sdks/logos/auth0_light_mode.png\" width=\"150\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout \u003ca href=\"https://auth0.com/why-auth0\"\u003eWhy Auth0?\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  This project is licensed under the MIT license. See the \u003ca href=\"./LICENSE\"\u003e LICENSE\u003c/a\u003e file for more info.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauth0%2Fnode-auth0","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauth0%2Fnode-auth0","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauth0%2Fnode-auth0/lists"}