@auth0/auth0-auth-js

The @auth0/auth0-auth-js library provides API's to interact with Auth0's Authentication Api's from withing JavaScript applications.

It contains methods to build Authorization URLs and Logout URLs, implement Backchannel Logout, verifying a logout token, to request Tokens using the Authorization Code Flow and Refresh Tokens, as well as retrieving a Token for a Connection, and managing Multi-Factor Authentication (MFA).

!Release
!Downloads

📚 Documentation - 🚀 Getting Started - 💬 Feedback

Documentation

- Examples - examples for your different use cases.
- Docs Site - explore our docs site and learn more about Auth0.

Getting Started

$3

``shell
npm i @auth0/auth0-auth-js
`

This library requires Node.js 20 LTS and newer LTS versions.

$3

Create an instance of the AuthClient. This instance will be imported and used anywhere we need access to the authentication methods.


`ts
import { AuthClient } from '@auth0/auth0-auth-js';

const authClient = new AuthClient({
domain: '',
clientId: '',
clientSecret: '',
});
`

The AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_CLIENT_SECRET can be obtained from the Auth0 Dashboard once you've created an application.

$3

Build the URL to redirect the user-agent to to request authorization at Auth0.

`ts
const authClient = new AuthClient({
// ...
authorizationParams: {
redirect_uri: '',
},
// ...
});

The AUTH0_REDIRECT_URI is needed to tell Auth0 what URL to redirect back to after successfull authentication, e.g. http://localhost:3000/auth/callback.
`

> [!IMPORTANT]
> You will need to register the AUTH0_REDIRECT_URI in your Auth0 Application as an Allowed Callback URL via the Auth0 Dashboard.

In order to build the authorization URL, call buildAuthorizationUrl(), and redirect the user to the returned URL.

`ts
const { authorizationUrl, codeVerifier } = await authClient.buildAuthorizationUrl();
`

- authorizationUrl: The URL to redirect the user to.
- codeVerifier: The code verifier that should be stored and used when exchanging the code for tokens.

$3

Build the URL to redirect the user-agent to to request logout at Auth0.

`ts
const logoutUrl = authClient.buildLogoutUrl({
returnTo: '',
});
`

> [!IMPORTANT]
> You will need to register the AUTH0_LOGOUT_RETURN_URL in your Auth0 Application as an Allowed Logout URL via the Auth0 Dashboard.

The AUTH0_LOGOUT_RETURN_URL is needed to tell Auth0 what URL to redirect back to after successfully logging out, e.g. http://localhost:3000.

$3

The SDK supports RFC 8693 OAuth 2.0 Token Exchange for first-party on-behalf-of flows, enabling secure token exchanges while preserving user identity.

#### When to Use Which Flow

- Custom Token Exchange: Use when you control the subject token format. Common scenarios:
- Exchanging MCP server tokens for Auth0 tokens
- Migrating from legacy authentication systems
- Federating with partner systems using custom token formats
- Exchanging tokens issued by your own services

- Access Token Exchange with Token Vault (via exchangeToken): Use when exchanging for external provider's access tokens:
- Accessing Google APIs with a user's Google token
- Calling Facebook Graph API with a user's Facebook token
- Any scenario where Auth0 manages the external provider's refresh tokens in the Token Vault

> Deprecated: getTokenForConnection() is deprecated. Use exchangeToken({ connection, subjectToken, subjectTokenType, ... }) instead.

#### Custom Token Exchange Example

> Note: In this SDK, Custom Token Exchange currently requires a confidential client. Supported client authentication methods: client_secret_post, private_key_jwt, and mTLS (via customFetch). Public clients are not yet supported by this method.

`ts
import { AuthClient } from '@auth0/auth0-auth-js';

const authClient = new AuthClient({
domain: '',
clientId: '',
clientSecret: '',
});

// Exchange a custom token (e.g., from an MCP server or legacy system)
// The subjectTokenType identifies your token format (configured in your Token Exchange Profile)
const response = await authClient.exchangeToken({
subjectTokenType: 'urn:example:custom-token', // Your custom token type URN
subjectToken: userAccessToken, // The token to exchange
audience: 'https://api.backend.com',
});

// Handle token expiry - check expiresAt and re-exchange when needed
// Note: expiresAt is in seconds, Date.now() is in milliseconds
const tokenIsValid = Math.floor(Date.now() / 1000) < response.expiresAt;
if (!tokenIsValid) {
// Re-exchange the token or use a refresh token if available
const refreshed = await authClient.exchangeToken({
subjectTokenType: 'urn:example:custom-token',
subjectToken: newSubjectToken,
audience: 'https://api.backend.com',
});
}
`

> Security Note: Never include PII, secrets, or sensitive data in the extra parameter.
> These values may be logged by Auth0 or intermediary systems. Use extra only for
> non-sensitive metadata like device IDs, session identifiers, or request context.

#### Token Vault Example

`ts
import { AuthClient } from '@auth0/auth0-auth-js';

const authClient = new AuthClient({
domain: '',
clientId: '',
clientSecret: '',
});

// Exchange an Auth0 access token for an external provider's access token (e.g., Google)
const response = await authClient.exchangeToken({
connection: 'google-oauth2',
subjectToken: auth0AccessToken,
subjectTokenType: 'urn:ietf:params:oauth:token-type:access_token',
loginHint: 'user@example.com', // Optional: specify which account when user has multiple
scope: 'https://www.googleapis.com/auth/calendar.readonly', // Optional: specific scopes
});

// Or exchange an Auth0 refresh token instead
const responseFromRefresh = await authClient.exchangeToken({
connection: 'google-oauth2',
subjectToken: auth0RefreshToken,
subjectTokenType: 'urn:ietf:params:oauth:token-type:refresh_token',
});

// Use the external provider's access token
console.log('External access token:', response.accessToken);
`

Learn more: Custom Token Exchange | Token Vault

$3

The SDK provides built-in support for managing Multi-Factor Authentication. You can enroll authenticators (OTP, SMS, email), list enrolled authenticators, challenge them for verification, and delete them.

`ts
// Access the MFA client via the authClient.mfa property
const mfaToken = '';

// Enroll an OTP authenticator (Google Authenticator, Auth0, etc.)
const enrollment = await authClient.mfa.enrollAuthenticator({
authenticatorTypes: ['otp'],
mfaToken
});

// List all enrolled authenticators
const authenticators = await authClient.mfa.listAuthenticators({ mfaToken });

// Challenge an authenticator
const challenge = await authClient.mfa.challengeAuthenticator({
challengeType: 'otp',
mfaToken
});

// Delete an authenticator
await authClient.mfa.deleteAuthenticator({
authenticatorId: 'totp|dev_abc123',
mfaToken
});
``

For detailed MFA examples including SMS enrollment, OOB challenges, and more, see the MFA section in EXAMPLES.md.

$3

A full overview of examples can be found in EXAMPLES.md.

Feedback

$3

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

- Auth0's general contribution guidelines
- Auth0's code of conduct guidelines
- This repo's contribution guide

$3

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.