Auth0Client - Auth0 Docs

Constructor

new Auth0Client(options: Auth0ClientOptions): Auth0Client

Parameters

Auth0ClientOptions

required

Type: Auth0ClientOptions

Returns

Auth0Client

Properties

MfaApiClient

required

MFA API client for multi-factor authentication operations.Provides methods for:

Listing enrolled authenticators
Enrolling new authenticators (OTP, SMS, Voice, Push, Email)
Initiating MFA challenges
Verifying MFA challenges

Type: MfaApiClient

MyAccountApiClient

required

Type: MyAccountApiClient

PasskeyApiClient

required

Passkey API client for passwordless authentication.Provides two single-call methods that handle the full WebAuthn flow internally:

signup(options) — register a new user with a passkey
login(options?) — authenticate an existing user with a passkey

Type: PasskeyApiClient

Methods

checkSession()

checkSession(options?: GetTokenSilentlyOptions): Promise<void>

await auth0.checkSession();

Check if the user is logged in using getTokenSilently. The difference with getTokenSilently is that this doesn’t return a token, but it will pre-fill the token cache. This method also heeds the auth0.{clientId}.is.authenticated cookie, as an optimization to prevent calling Auth0 unnecessarily. If the cookie is not present because there was no previous login (or it has expired) then tokens will not be refreshed. It should be used for silently logging in the user when you instantiate the Auth0Client constructor. You should not need this if you are using the createAuth0Client factory. Note: the cookie may not be present if running an app using a private tab, as some browsers clear JS cookie data and local storage when the tab or page is closed, or on page reload. This effectively means that checkSession could silently return without authenticating the user on page refresh when using a private tab, despite having previously logged in. As a workaround, use getTokenSilently instead and handle the possible login_required error as shown in the readme.

Parameters

GetTokenSilentlyOptions

Type: GetTokenSilentlyOptions

Returns

Promise<void>

connectAccountWithRedirect()

connectAccountWithRedirect(options: RedirectConnectAccountOptions<TAppState>): Promise<void>

Initiates a redirect to connect the user’s account with a specified connection. This method generates PKCE parameters, creates a transaction, and redirects to the /connect endpoint. You must enable Offline Access from the Connection Permissions settings to be able to use the connection with Connected Accounts.

Parameters

RedirectConnectAccountOptions<TAppState>

required

Options for the connect account redirect flow.Type: RedirectConnectAccountOptions

Returns

Promise<void> Resolves when the redirect is initiated.

createFetcher()

createFetcher(config?: FetcherConfig<TOutput>): Fetcher<TOutput>

Returns a new Fetcher class that will contain a fetchWithAuth() method. This is a drop-in replacement for the Fetch API’s fetch() method, but will handle certain authentication logic for you, like building the proper auth headers or managing DPoP nonces and retries automatically. Check the EXAMPLES.md file for a deeper look into this method.

Parameters

FetcherConfig<TOutput>

Type: FetcherConfig

Returns

Fetcher<TOutput>

customTokenExchange()

customTokenExchange(options: CustomTokenExchangeOptions): Promise<TokenEndpointResponse>

await auth0.customTokenExchange(options);

Exchanges an external subject token for Auth0 tokens without affecting the current session. Unlike loginWithCustomTokenExchange, this method has no side effects — it does not cache tokens, does not update the authenticated session, and does not affect isAuthenticated() or getUser(). Use this for delegation or impersonation scenarios where you need a token for a downstream API but do not want to change who the current user is. When a Web Worker is configured, the refresh_token is discarded inside the worker and never reaches the main thread. When no Web Worker is configured, the raw authorization server response is returned — if a refresh_token is present, discard it; this method intentionally does not store it.

Parameters

CustomTokenExchangeOptions

required

The options required to perform the token exchange.Type: CustomTokenExchangeOptions

Returns

Promise<TokenEndpointResponse> A promise that resolves to the token endpoint response. Example:

const tokenResponse = await auth0.customTokenExchange({
  subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
  subject_token_type: 'urn:acme:legacy-system-token',
  actor_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',
  actor_token_type: 'https://idp.example.com/token-type/agent',
  audience: 'https://api.example.com',
});

// Use tokenResponse.access_token to call downstream API
// Current user session is unchanged

exchangeToken()

exchangeToken(options: CustomTokenExchangeOptions): Promise<TokenEndpointResponse>

Parameters

CustomTokenExchangeOptions

required

The options required to perform the token exchange.Type: CustomTokenExchangeOptions

Returns

Promise<TokenEndpointResponse> A promise that resolves to the token endpoint response. Example:

// Instead of:
const tokens = await auth0.exchangeToken(options);

// Use:
const tokens = await auth0.loginWithCustomTokenExchange(options);

generateDpopProof()

generateDpopProof(params: { accessToken: string; method: string; nonce: string; url: string }): Promise<string>

Returns a string to be used to demonstrate possession of the private key used to cryptographically bind access tokens with DPoP. It requires enabling the Auth0ClientOptions.useDpop option.

Parameters

{ accessToken: string; method: string; nonce: string; url: string }

required

Returns

Promise<string>

getConfiguration()

getConfiguration(): Readonly<ClientConfiguration>

Returns a readonly copy of the initialization configuration.

const auth0 = new Auth0Client({
  domain: 'tenant.auth0.com',
  clientId: 'abc123'
});

const config = auth0.getConfiguration();
// { domain: 'tenant.auth0.com', clientId: 'abc123' }

Returns

Readonly<ClientConfiguration> An object containing domain and clientId

getDpopNonce()

getDpopNonce(id?: string): Promise<undefined | string>

Returns the current DPoP nonce used for making requests to Auth0. It can return undefined because when starting fresh it will not be populated until after the first response from the server. It requires enabling the Auth0ClientOptions.useDpop option.

Parameters

string

The identifier of a nonce: if absent, it will get the nonce used for requests to Auth0. Otherwise, it will be used to select a specific non-Auth0 nonce.

Returns

Promise<undefined | string>

getIdTokenClaims()

getIdTokenClaims(): Promise<undefined | IdToken>

const claims = await auth0.getIdTokenClaims();

Returns all claims from the id_token if available.

Returns

Promise<undefined | IdToken>

getTokenSilently()

getTokenSilently(options: GetTokenSilentlyOptions & { detailedResponse: true }): Promise<GetTokenSilentlyVerboseResponse>

Fetches a new access token and returns the response from the /oauth/token endpoint, omitting the refresh token.

Parameters

GetTokenSilentlyOptions & { detailedResponse: true }

required

Type: GetTokenSilentlyOptions

Returns

Promise<GetTokenSilentlyVerboseResponse>

getTokenSilently(options?: GetTokenSilentlyOptions): Promise<string>

Fetches a new access token and returns it.

Parameters

GetTokenSilentlyOptions

Type: GetTokenSilentlyOptions

Returns

Promise<string>

getTokenWithPopup()

getTokenWithPopup(options?: GetTokenWithPopupOptions, config?: PopupConfigOptions): Promise<undefined | string>

const token = await auth0.getTokenWithPopup(options);

Parameters

GetTokenWithPopupOptions

Type: GetTokenWithPopupOptions

PopupConfigOptions

Type: PopupConfigOptions

Returns

Promise<undefined | string>

getUser()

getUser(): Promise<undefined | TUser>

const user = await auth0.getUser();

Returns the user information if available (decoded from the id_token).

Returns

Promise<undefined | TUser>

handleRedirectCallback()

handleRedirectCallback(url?: string): Promise<RedirectLoginResult<TAppState> | ConnectAccountRedirectResult<TAppState>>

After the browser redirects back to the callback page, call handleRedirectCallback to handle success and error responses from Auth0. If the response is successful, results will be valid according to their expiration times.

Parameters

string

Returns

Promise<RedirectLoginResult<TAppState> | ConnectAccountRedirectResult<TAppState>>

isAuthenticated()

isAuthenticated(): Promise<boolean>

const isAuthenticated = await auth0.isAuthenticated();

Returns true if there’s valid information stored, otherwise returns false.

Returns

Promise<boolean>

loginWithCustomTokenExchange()

loginWithCustomTokenExchange(options: CustomTokenExchangeOptions): Promise<TokenEndpointResponse>

Parameters

CustomTokenExchangeOptions

required

Type: CustomTokenExchangeOptions

Returns

Promise<TokenEndpointResponse>

loginWithPopup()

loginWithPopup(options?: PopupLoginOptions, config?: PopupConfigOptions): Promise<void>

try {
 await auth0.loginWithPopup(options);
} catch(e) {
 if (e instanceof PopupCancelledError) {
   // Popup was closed before login completed
 }
}

Opens a popup with the /authorize URL using the parameters provided as arguments. Random and secure state and nonce parameters will be auto-generated. If the response is successful, results will be valid according to their expiration times. IMPORTANT: This method has to be called from an event handler that was started by the user like a button click, for example, otherwise the popup will be blocked in most browsers.

Parameters

PopupLoginOptions

Type: PopupLoginOptions

PopupConfigOptions

Type: PopupConfigOptions

Returns

Promise<void>

loginWithRedirect()

loginWithRedirect(options?: RedirectLoginOptions<TAppState>): Promise<void>

await auth0.loginWithRedirect(options);

Performs a redirect to /authorize using the parameters provided as arguments. Random and secure state and nonce parameters will be auto-generated.

Parameters

RedirectLoginOptions<TAppState>

Type: RedirectLoginOptions

Returns

Promise<void>

logout()

logout(options?: LogoutOptions): Promise<void>

await auth0.logout(options);

Clears the application session and performs a redirect to /v2/logout, using the parameters provided as arguments, to clear the Auth0 session. If the federated option is specified it also clears the Identity Provider session. Read more about how Logout works at Auth0.

Parameters

LogoutOptions

Type: LogoutOptions

Returns

Promise<void>

revokeRefreshToken()

revokeRefreshToken(options?: RevokeRefreshTokenOptions): Promise<void>

await auth0.revokeRefreshToken();

Revokes the refresh token using the /oauth/revoke endpoint. This invalidates the refresh token so it can no longer be used to obtain new access tokens. The method works with both memory and localStorage cache modes:

For memory storage with worker: The refresh token never leaves the worker thread, maintaining security isolation
For localStorage: The token is retrieved from cache and revoked

If useRefreshTokens is disabled, this method does nothing. Online mode: when refreshTokenMode is 'online', revoking the ORT via /oauth/revoke also terminates the Auth0 session and clears the entire local cache (access token, ID token, user profile). Because Online Refresh Tokens are session-bound, the authorization server ties the token directly to the session — revoking the ORT invalidates the session server-side. The local cache is cleared immediately so that isAuthenticated() returns false and getUser() returns undefined right away, without waiting for the access token to expire. Use this when you need to force a sign-out without a redirect (e.g. background revocation). For a redirect-based sign-out, prefer logout(). Important: This method revokes the refresh token for a single audience. If your application requests tokens for multiple audiences, each audience may have its own refresh token. To fully revoke all refresh tokens, call this method once per audience. If you want to terminate the user’s session with a redirect, use logout() instead. When using Multi-Resource Refresh Tokens (MRRT), a single refresh token may cover multiple audiences. In that case, revoking it will affect all cache entries that share the same token.

// Revoke the default refresh token
await auth0.revokeRefreshToken();

Parameters

RevokeRefreshTokenOptions

Optional parameters to identify which refresh token to revoke. Defaults to the audience configured in authorizationParams.Type: RevokeRefreshTokenOptions

Returns

Promise<void>

setDpopNonce()

setDpopNonce(nonce: string, id?: string): Promise<void>

Sets the current DPoP nonce used for making requests to Auth0. It requires enabling the Auth0ClientOptions.useDpop option.

Parameters

string

required

The nonce value.

string

The identifier of a nonce: if absent, it will set the nonce used for requests to Auth0. Otherwise, it will be used to select a specific non-Auth0 nonce.

Returns

Promise<void>

​Constructor

​Parameters

​Returns

​Properties

​Methods

​checkSession()

​Parameters

​Returns

​connectAccountWithRedirect()

​Parameters

​Returns

​createFetcher()

​Parameters

​Returns

​customTokenExchange()

​Parameters

​Returns

​exchangeToken()

​Parameters

​Returns

​generateDpopProof()

​Parameters

​Returns

​getConfiguration()

​Returns

​getDpopNonce()

​Parameters

​Returns

​getIdTokenClaims()

​Returns

​getTokenSilently()

​Parameters

​Returns

​Parameters

​Returns

​getTokenWithPopup()

​Parameters

​Returns

​getUser()

​Returns

​handleRedirectCallback()

​Parameters

​Returns

​isAuthenticated()

​Returns

​loginWithCustomTokenExchange()

​Parameters

​Returns

​loginWithPopup()

​Parameters

​Returns

​loginWithRedirect()

​Parameters

​Returns

​logout()

​Parameters

​Returns

​revokeRefreshToken()

​Parameters

​Returns

​setDpopNonce()

​Parameters

​Returns

Constructor

Parameters

Returns

Properties

Methods

checkSession()

Parameters

Returns

connectAccountWithRedirect()

Parameters

Returns

createFetcher()

Parameters

Returns

customTokenExchange()

Parameters

Returns

exchangeToken()

Parameters

Returns

generateDpopProof()

Parameters

Returns

getConfiguration()

Returns

getDpopNonce()

Parameters

Returns

getIdTokenClaims()

Returns

getTokenSilently()

Parameters

Returns

Parameters

Returns

getTokenWithPopup()

Parameters

Returns

getUser()

Returns

handleRedirectCallback()

Parameters

Returns

isAuthenticated()

Returns

loginWithCustomTokenExchange()

Parameters

Returns

loginWithPopup()

Parameters

Returns

loginWithRedirect()

Parameters

Returns

logout()

Parameters

Returns

revokeRefreshToken()

Parameters

Returns

setDpopNonce()

Parameters

Returns