Auth0 Spa Js

https://github.com/auth0/auth0-spa-js
Admin
Auth0 SDK for Single Page Applications using Authorization Code Grant Flow with PKCE
Tokens:225,980
Snippets:1,812
Trust Score:9.7
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Set up and run the SDK Playground

Source: https://github.com/auth0/auth0-spa-js/blob/main/DEVELOPMENT.md

Installs dependencies and starts the Vue.js Playground app on http://localhost:3000.

```bash
# Install dependencies
npm i

# Run the playground app
npm start
```

--------------------------------

### Complete Granular Signup Example

Source: https://github.com/auth0/auth0-spa-js/blob/main/examples/passkeys.md

Full granular signup flow: get challenge, create credential, and exchange for tokens. Throws an error if credential creation is cancelled.

```javascript
async function granularSignup(email, displayName) {
  // Step 1: Get challenge
  const challenge = await auth0.passkey.getSignupChallenge({
    email,
    name: displayName
  });

  // Step 2: Create credential
  const credential = await navigator.credentials.create({
    publicKey: challenge.publicKey
  });

  if (!credential) {
    throw new Error('Credential creation cancelled');
  }

  // Step 3: Exchange for tokens
  const tokens = await auth0.passkey.getTokenWithPasskey({
    authSession: challenge.authSession,
    credential
  });

  return tokens;
}
```

--------------------------------

### Install @auth0/auth0-spa-js via npm

Source: https://github.com/auth0/auth0-spa-js/blob/main/README.md

Install the Auth0 SPA SDK using npm in your project directory.

```sh
npm install @auth0/auth0-spa-js
```

--------------------------------

### Complete Passkey Flow Example

Source: https://github.com/auth0/auth0-spa-js/blob/main/examples/passkeys.md

Complete example showing client initialization and simplified signup and login functions using auth0.passkey.signup() and auth0.passkey.login().

```javascript
import { createAuth0Client } from '@auth0/auth0-spa-js';

const auth0 = await createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  clientId: '<AUTH0_CLIENT_ID>',
  useRefreshTokens: true,
  authorizationParams: {
    redirect_uri: '<MY_CALLBACK_URL>'
  }
});

// --- Signup (single call) ---
async function signupWithPasskey(email, displayName) {
  await auth0.passkey.signup({ email, name: displayName });
  return await auth0.getUser();
}

// --- Login (single call) ---
async function loginWithPasskey() {
  await auth0.passkey.login();
  return await auth0.getUser();
}
```

--------------------------------

### Complete Granular Login Example

Source: https://github.com/auth0/auth0-spa-js/blob/main/examples/passkeys.md

Full granular login flow: get challenge, get credential, and exchange for tokens. Throws an error if credential assertion is cancelled.

```javascript
async function granularLogin() {
  // Step 1: Get challenge
  const challenge = await auth0.passkey.getLoginChallenge();

  // Step 2: Get credential
  const credential = await navigator.credentials.get({
    publicKey: challenge.publicKey
  });

  if (!credential) {
    throw new Error('Credential assertion cancelled');
  }

  // Step 3: Exchange for tokens
  const tokens = await auth0.passkey.getTokenWithPasskey({
    authSession: challenge.authSession,
    credential
  });

  return tokens;
}
```

--------------------------------

### Complete MFA Flow Example

Source: https://github.com/auth0/auth0-spa-js/blob/main/examples/mfa.md

Shows the full MFA flow: checks for MFA required, gets enrollment factors, enrolls with OTP, or challenges with OTP/OOB, and verifies. Uses MfaRequiredError and methods like getEnrollmentFactors, enroll, verify, getAuthenticators, and challenge.

```javascript
async function handleMfaFlow() {
  try {
    await auth0.getTokenSilently();
  } catch (error) {
    if (error instanceof MfaRequiredError) {
      const mfaToken = error.mfa_token;

      // Check if enrollment is needed
      const enrollmentFactors = await auth0.mfa.getEnrollmentFactors(mfaToken);

      if (enrollmentFactors.length > 0) {
        // User needs to enroll
        const selectedFactor = await showEnrollmentUI(enrollmentFactors);

        // Enroll based on user selection
        if (selectedFactor.type === 'otp') {
          const enrollment = await auth0.mfa.enroll({
            mfaToken: mfaToken,
            factorType: 'otp'
          });
          await showQRCode(enrollment.barcodeUri);

          // User scans QR and enters code to verify enrollment
          const verifyCode = await promptUserForCode();
          const tokens = await auth0.mfa.verify({
            mfaToken: mfaToken,
            otp: verifyCode
          });

          return tokens;
        }
      } else {
        // User has authenticators - proceed with challenge
        const authenticators = await auth0.mfa.getAuthenticators(mfaToken);
        const selected = await showAuthenticatorPicker(authenticators);

        // Initiate challenge
        const challenge = await auth0.mfa.challenge({
          mfaToken: mfaToken,
          challengeType: selected.type === 'otp' ? 'otp' : 'oob',
          authenticatorId: selected.id
        });

        // Get code from user
        const code = await promptUserForCode();

        // Verify
        const tokens = await auth0.mfa.verify({
          mfaToken: mfaToken,
          otp: selected.type === 'otp' ? code : undefined,
          oobCode: selected.type !== 'otp' ? challenge.oobCode : undefined,
          bindingCode: selected.type !== 'otp' ? code : undefined
        });

        return tokens;
      }
    }
  }
}
```

--------------------------------

### connectAccount usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/my-account-api-client.md

Usage example for connectAccount. It obtains the connect URI, ticket, and auth session for the Connected Accounts flow. The example then redirects the user to the connect URI with the ticket as a query parameter.

```js
const { connect_uri, connect_params, auth_session } =
  await auth0.myAccount.connectAccount({
    connection: 'google-oauth2',
    scopes: ['https://www.googleapis.com/auth/calendar'],
    redirect_uri: window.location.origin,
    state: 'abc',
    code_challenge: 'challenge',
    code_challenge_method: 'S256'
  });
window.location.assign(`${connect_uri}?ticket=${connect_params.ticket}`);
```

--------------------------------

### Get Signup Challenge

Source: https://github.com/auth0/auth0-spa-js/blob/main/examples/passkeys.md

Request a passkey signup challenge to start the granular signup flow. The returned challenge contains an authSession to save and a publicKey to pass to navigator.credentials.create().

```javascript
const challenge = await auth0.passkey.getSignupChallenge({
  email: 'user@example.com',
  name: 'Jane Doe' // optional display name
});

// challenge.authSession — save this to complete signup later
// challenge.publicKey — pass to navigator.credentials.create()
```

--------------------------------

### completeAccount usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/my-account-api-client.md

Usage example for completeAccount. Passes the auth_session, connect_code, redirect_uri, and optional code_verifier. Logs the returned id, connection, and expires_at.

```js
const completed = await auth0.myAccount.completeAccount({
  auth_session,
  connect_code,
  redirect_uri: window.location.origin,
  code_verifier
});
console.log(completed.id, completed.connection, completed.expires_at);
```

--------------------------------

### getUser usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client-session.md

Usage example for getUser. Shows basic retrieval and typed retrieval with a custom interface extending User.

```js
const user = await auth0.getUser();
console.log(user?.email, user?.sub);

interface AppUser extends User { roles?: string[] }
const typed = await auth0.getUser<AppUser>();
console.log(typed?.roles);
```

--------------------------------

### getConfiguration usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client.md

Example of calling getConfiguration() and the resulting configuration object. The comment shows the expected output.

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

--------------------------------

### loginWithPopup(options?, config?)

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/Auth0Client.html

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.

```APIDOC
## loginWithPopup(options?, config?)

### Description
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.

### Method
loginWithPopup

### Parameters
- `Optional` options: PopupLoginOptions
- `Optional` config: PopupConfigOptions

### Returns
Promise<void>
```

--------------------------------

### Signup with email and audience

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/passkey-api-client.md

Example of calling signup with email and audience, then logging the access token.

```js
const tokens = await auth0.passkey.signup({
  email: 'user@example.com',
  audience: 'https://api.example.com'
});
console.log(tokens.access_token);
```

--------------------------------

### getLoginChallenge usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/passkey-api-client.md

JavaScript example showing the full two-step flow: getLoginChallenge, then navigator.credentials.get, then getTokenWithPasskey. This is the basic usage without error handling.

```js
const { authSession, publicKey } = await auth0.passkey.getLoginChallenge();
const assertion = await navigator.credentials.get({ publicKey });
const tokens = await auth0.passkey.getTokenWithPasskey({ authSession, credential: assertion });
```

--------------------------------

### loginWithPopup usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client.md

Example of calling loginWithPopup from a user-gesture event handler, handling success and errors.

```javascript
// Must be called from a user-gesture event handler
document.getElementById('login-popup').addEventListener('click', async () => {
  try {
    await auth0.loginWithPopup({
      authorizationParams: { audience: 'https://api.example.com' }
    });
    const isAuthed = await auth0.isAuthenticated(); // true
  } catch (e) {
    if (e instanceof PopupCancelledError) {
      // user closed the popup — do nothing
    } else {
      console.error('Popup login failed', e);
    }
  }
});
```

--------------------------------

### Signup with error handling for passkey_not_supported

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/passkey-api-client.md

Example of handling the passkey_not_supported error by falling back to password login.

```js
try {
  await auth0.passkey.signup({
    email: 'user@example.com',
    realm: 'my-realm',
    organization: 'org_123'
  });
} catch (e) {
  if (e instanceof PasskeyError && e.code === 'passkey_not_supported') {
    fallbackToPasswordLogin();
  }
}
```

--------------------------------

### getIdTokenClaims usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client-session.md

Usage example for getIdTokenClaims. Logs exp, org_id, and session_expiry claims.

```js
const claims = await auth0.getIdTokenClaims();
console.log(claims?.exp, claims?.org_id, claims?.session_expiry);
```

--------------------------------

### getConfiguration() example

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/Auth0Client.html

Creates an Auth0Client instance and retrieves its configuration using getConfiguration(). The returned config object contains the domain and clientId.

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

--------------------------------

### scope example

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/types/CustomTokenExchangeOptions.html

Example of a space-separated list of OAuth 2.0 scopes being requested. Subject to API authorization policies configured in Auth0.

```text
"openid profile email read:data write:data"
```

--------------------------------

### logout Usage Example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/anonymous-session-api-client.md

JavaScript example showing how to call logout to end the anonymous session and clear local tokens.

```js
await auth0.anonymous.logout();
```

--------------------------------

### Usage example: getTokenSilently with fetch

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/anonymous-session-api-client.md

JavaScript example showing how to obtain an anonymous access token and use it in an Authorization header for a fetch request.

```js
const { accessToken } = await auth0.anonymous.getTokenSilently({
  audience: 'https://api.example.com'
});
await fetch('https://api.example.com/me', {
  headers: { authorization: `Bearer ${accessToken}` }
});
```

--------------------------------

### audience example

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/types/CustomTokenExchangeOptions.html

Example of the target audience for the requested Auth0 token. Must match exactly with an API identifier configured in your Auth0 tenant. If not provided, falls back to the client's default audience.

```text
"https://api.your-service.com/v1"
```

--------------------------------

### connectAccountWithRedirect usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client-advanced.md

Example of calling connectAccountWithRedirect with a connection, scopes, and appState. The redirectUri defaults to authorizationParams.redirect_uri or window.location.origin.

```javascript
await auth0.connectAccountWithRedirect({
  connection: 'google-oauth2',
  scopes: ['https://www.googleapis.com/auth/calendar'],
  appState: { returnTo: '/settings' }
});
```

--------------------------------

### loginWithPopup manual popup lifecycle example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client.md

Example of manually managing the popup lifecycle for Chrome extensions, using closePopup: false.

```javascript
// Manual popup lifecycle (Chrome extensions): closePopup: false
const popup = window.open('', '_blank');
try {
  await auth0.loginWithPopup(
    { authorizationParams: { screen_hint: 'signup' } },
    { popup, closePopup: false, timeoutInSeconds: 90 }
  );
} finally {
  popup?.close();
}
```

--------------------------------

### loginWithCustomTokenExchange: Full example with options

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/Auth0Client.html

Example usage of `loginWithCustomTokenExchange` with a full options object and error handling. The request includes `grant_type`, `subject_token`, `subject_token_type`, `scope`, `audience`, and optional `organization`. After success, `getUser()` can be used to access user info.

```javascript
const options = {  subject_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...',  subject_token_type: 'urn:acme:legacy-system-token',  scope: 'openid profile email',  audience: 'https://api.example.com',  organization: 'org_12345'};try {  const tokenResponse = await auth0.loginWithCustomTokenExchange(options);  console.log('Access token:', tokenResponse.access_token);  // User is now logged in - access user info  const user = await auth0.getUser();  console.log('Logged in user:', user);} catch (error) {  console.error('Token exchange failed:', error);}
```

--------------------------------

### getFactors usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/my-account-api-client.md

Usage example for getFactors. Iterates over the returned factors and logs each factor's type and usage.

```js
const factors = await auth0.myAccount.getFactors();
factors.forEach(f => console.log(f.type, f.usage));
```

--------------------------------

### getConfiguration

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/Auth0Client.html

Gets the client configuration.

```APIDOC
## getConfiguration

### Description
Gets the client configuration.

### Method
method

### Returns
- **object** - The client configuration.
```

--------------------------------

### mintTransferToken Usage Example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/anonymous-session-api-client.md

JavaScript example showing how to call mintTransferToken and pass the ticket to loginWithRedirect via authorizationParams. Called internally by loginWithRedirect/loginWithPopup.

```js
// Called internally by loginWithRedirect/loginWithPopup via _applyAnonTransferToken
const ticket = await auth0.anonymous.mintTransferToken();
if (ticket) {
  await auth0.loginWithRedirect({
    authorizationParams: { anon_transfer_token: ticket }
  });
}
```

--------------------------------

### logout with returnTo and openUrl

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client-session.md

Usage example for logout with a returnTo URL and custom openUrl handler.

```js
await auth0.logout({
  logoutParams: { returnTo: 'https://myapp.com/goodbye' },
  openUrl: url => { window.location.assign(url); }
});
```

--------------------------------

### enrollmentChallenge

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/MyAccountApiClient.html

Starts the enrollment of an authentication method.

```APIDOC
## enrollmentChallenge(options)

### Description
Start the enrollment of an authentication method for the current user. The response shape varies by type.

### Parameters
- **options** (EnrollmentChallengeOptions) - Required - Enrollment challenge options specifying the factor type and any type-specific fields.

### Returns
- **Promise<EnrollmentChallengeResponse>** - A promise that resolves to the enrollment challenge response (shape varies by type).
```

--------------------------------

### GET /me/v1/authentication-methods

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/endpoints.md

Lists authentication methods. Optional type query parameter. Requires the read:me:authentication_methods scope.

```APIDOC
## GET /me/v1/authentication-methods

### Description
Lists authentication methods. Optional `type` query parameter. Requires the `read:me:authentication_methods` scope.

### Method
GET

### Endpoint
/me/v1/authentication-methods

### Query Parameters
- **type** (string) - Optional - Filter by type.

### Scope
`read:me:authentication_methods`

### Success Response
`{ authentication_methods: AuthenticationMethod[] }`

### Error Response
`MyAccountApiError`
```

--------------------------------

### enrollmentChallenge

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/MyAccountApiClient.html

Starts the enrollment challenge for a new authentication method.

```APIDOC
## enrollmentChallenge

### Description
Starts the enrollment challenge for a new authentication method.

### Parameters
- **options** (object) - Required - Options for the enrollment challenge.

### Returns
A Promise that resolves with the challenge result.
```

--------------------------------

### challenge usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/mfa-api-client.md

JavaScript example calling auth0.mfa.challenge with an oob challenge type and an authenticatorId. The returned oobCode is passed to verify() in a later step.

```js
const challenge = await auth0.mfa.challenge({
  mfaToken,
  challengeType: 'oob',
  authenticatorId: 'sms|dev_xxx'
});
console.log(challenge.oobCode); // passed to verify() below
```

--------------------------------

### Basic usage - create client at app startup

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/create-auth0-client.md

Example of creating an Auth0Client at app startup using createAuth0Client with domain, clientId, and authorizationParams.

```js
import { createAuth0Client } from '@auth0/auth0-spa-js';

async function bootstrap() {
  const auth0 = await createAuth0Client({
    domain: 'tenant.us.auth0.com',
    clientId: 'aBcD123',
    authorizationParams: {
      redirect_uri: window.location.origin,
      audience: 'https://api.example.com',
      scope: 'openid profile email read:data'
    }
  });
  window.auth0 = auth0;
}
bootstrap();
```

--------------------------------

### Catch MfaEnrollmentFactorsError when getting enrollment factors

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/MfaEnrollmentFactorsError.html

Example of catching MfaEnrollmentFactorsError when getting enrollment factors fails. The error object exposes error and error_description properties, which can be logged or handled.

```javascript
try {
  const factors = await mfa.getEnrollmentFactors(mfaToken);
} catch (error) {
  if (error instanceof MfaEnrollmentFactorsError) {
    console.log(error.error); // 'mfa_context_not_found'
    console.log(error.error_description); // 'MFA context not found...'
  }
}
```

--------------------------------

### POST {apiBase}v1/authentication-methods

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/my-account-api-client.md

Starts enrollment for a factor type. The response derives `id` and `location` from the `Location` response header.

```APIDOC
## POST {apiBase}v1/authentication-methods

### Description
Starts enrollment for a factor type. The response derives `id` and `location` from the `Location` response header.

### Method
POST

### Endpoint
`{apiBase}v1/authentication-methods`

### Parameters
#### Request Body
- **options** (`EnrollmentChallengeOptions`) - Required - Discriminated union on `type` (`'passkey' | 'phone' | 'email' | 'totp' | 'push-notification' | 'recovery-code' | 'password'`); see [types-myaccount.md](../types-myaccount.md) for per-type fields

### Request Example
```js
const challenge = await auth0.myAccount.enrollmentChallenge({
  type: 'totp'
});
```

### Response
#### Success Response
- **id** (string) - Derived from the `Location` response header
- **location** (string) - Derived from the `Location` response header
- **auth_session** (string) - Authentication session identifier
- **barcode_uri** (string) - Type-specific field for TOTP
- **manual_input_code** (string) - Type-specific field for TOTP
- **recovery_code** (string) - Type-specific field for recovery code
- **policy** (object) - Type-specific field for password
- **authn_params_public_key** (object) - Type-specific field for passkey

#### Response Example
```js
console.log(challenge.barcode_uri, challenge.manual_input_code);
```
```

--------------------------------

### Basic usage with createAuth0Client

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/index.md

Shows the recommended way to initialize the Auth0 client using createAuth0Client, then perform a login redirect, handle the callback, and retrieve the user profile. Replace 'example.auth0.com' and 'YOUR_CLIENT_ID' with your actual Auth0 domain and client ID.

```js
import { createAuth0Client } from '@auth0/auth0-spa-js';

const auth0 = await createAuth0Client({
  domain: 'example.auth0.com',
  clientId: 'YOUR_CLIENT_ID',
  authorizationParams: {
    redirect_uri: window.location.origin
  }
});

// login → callback route
await auth0.loginWithRedirect();
const result = await auth0.handleRedirectCallback();
const user = await auth0.getUser();
```

--------------------------------

### Get Login Challenge

Source: https://github.com/auth0/auth0-spa-js/blob/main/examples/passkeys.md

Request a passkey login challenge to start the granular login flow. The realm option is optional. The returned challenge contains an authSession and a publicKey for navigator.credentials.get().

```javascript
const challenge = await auth0.passkey.getLoginChallenge({
  realm: 'Username-Password-Authentication' // optional
});

// challenge.authSession — save this to complete login later
// challenge.publicKey — pass to navigator.credentials.get()
```

--------------------------------

### OTP challenge example

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/MfaApiClient.html

Initiates an OTP challenge using the mfa.challenge method. Requires mfaToken and challengeType 'otp'.

```typescript
const challenge = await mfa.challenge({  mfaToken: mfaTokenFromLogin,  challengeType: 'otp',  authenticatorId: 'otp|dev_xxx'});// User enters OTP from their authenticator app
```

--------------------------------

### LocalStorageCache

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/cache.md

LocalStorageCache is a cache implementation that stores JSON-serialized entries in `window.localStorage`, scoped to keys starting with `@@auth0spajs@@`. It provides methods to set, get, remove, and list all cache keys.

```APIDOC
## LocalStorageCache

### Description
Stores JSON-serialized entries under `window.localStorage`, scoped to keys starting with `@@auth0spajs@@`. `get` returns `undefined` on parse failure. Used when `cacheLocation: 'localstorage'`.

### Class
`LocalStorageCache`

### Methods

#### set

```ts
public set<T = Cacheable>(key: string, entry: T): void;
```

- **key** (string) - Required - The cache key.
- **entry** (T) - Required - The entry to store.

#### get

```ts
public get<T = Cacheable>(key: string): MaybePromise<T | undefined>;
```

- **key** (string) - Required - The cache key.
- **Returns**: The cached entry, or `undefined` if not found or on parse failure.

#### remove

```ts
public remove(key: string): void;
```

- **key** (string) - Required - The cache key to remove.

#### allKeys

```ts
public allKeys(): string[];
```

- **Returns**: An array of all cache keys.

### Usage

```js
import { LocalStorageCache } from '@auth0/auth0-spa-js';

const auth0 = new Auth0Client({
  domain, clientId,
  cache: new LocalStorageCache()
});
```
```

--------------------------------

### createAuth0Client

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/create-auth0-client.md

Documentation for the createAuth0Client factory function, including overloads, parameters, return type, errors, and usage examples.

```APIDOC
## createAuth0Client

### Description
Entry-point factory that constructs an `Auth0Client` and immediately calls `checkSession()` before resolving.

### Method
async function

### Endpoint
`createAuth0Client(options: Auth0ClientOptions): Promise<Auth0Client>`

### Parameters
#### Path Parameters
- **options** (`Auth0ClientOptions`) - Required - Full client configuration; see configuration.md for the complete option table.

### Request Example
```js
import { createAuth0Client } from '@auth0/auth0-spa-js';

async function bootstrap() {
  const auth0 = await createAuth0Client({
    domain: 'tenant.us.auth0.com',
    clientId: 'aBcD123',
    authorizationParams: {
      redirect_uri: window.location.origin,
      audience: 'https://api.example.com',
      scope: 'openid profile email read:data'
    }
  });
  window.auth0 = auth0;
}
bootstrap();
```

### Response
#### Success Response
- **Promise<Auth0Client>** - A fully initialized client whose token cache has already been pre-filled via `checkSession()` (silent session restore). If no session exists, it resolves anyway with an unauthenticated client.

#### Response Example
```js
const auth0 = await createAuth0Client({ /* options */ });
```

### Error Handling
- **InvalidConfigurationError** - Thrown when `refreshTokenMode: 'online'` is set without `useRefreshTokens: true` or without `useDpop: true`.
- **Error** (`Invalid cache location "<x>"`) - Thrown when `cacheLocation` is neither `'memory'` nor `'localstorage'`.
- **GenericError / network errors** - Propagated from the internal `checkSession()` → `getTokenSilently()` call; `login_required` from silent auth is swallowed by `checkSession()` itself.
```

--------------------------------

### getTokenSilently verbose response with cache-only mode

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client-tokens.md

JavaScript example using cacheMode 'cache-only' and detailedResponse true to get the full token response without network calls. The result includes access_token, id_token, and expires_in.

```javascript
// Verbose response + cache-only mode
const res = await auth0.getTokenSilently({
  cacheMode: 'cache-only',
  detailedResponse: true,
  authorizationParams: { audience: 'https://api.example.com' }
});
if (res) {
  console.log(res.access_token, res.id_token, res.expires_in);
}
```

--------------------------------

### openUrl example: custom redirect with window.location.replace

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/interfaces/RedirectLoginOptions.html

Shows how to use the openUrl option to control the redirect by replacing the current URL.

```typescript
const client = new Auth0Client({  openUrl(url) {    window.location.replace(url);  }});
```

--------------------------------

### Common npm commands for testing, linting, dev server, and build

Source: https://github.com/auth0/auth0-spa-js/blob/main/CLAUDE.md

Run unit tests with coverage, lint the codebase, start a dev server with live reload on localhost:3000, and produce a production build with UMD, ESM, CJS, and worker bundles. The build also runs test:es-check.

```bash
# Unit tests (with coverage)
npm test

# Lint
npm run lint

# Dev server with live reload (http://localhost:3000)
npm run dev

# Production build (UMD + ESM + CJS + worker bundles; runs test:es-check)
npm run build
```

--------------------------------

### signup

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/passkey-api-client.md

Registers a new user with a passkey. Requests a signup challenge, runs the browser credential-creation ceremony, serializes the credential (base64url), and exchanges it for tokens using the `urn:okta:params:oauth:grant-type:webauthn` grant.

```APIDOC
## [POST] /passkey/signup

### Description
Registers a new user with a passkey. Requests a signup challenge, runs the browser credential-creation ceremony, serializes the credential (base64url), and exchanges it for tokens using the `urn:okta:params:oauth:grant-type:webauthn` grant.

### Method
POST

### Endpoint
`auth0.passkey.signup(options)`

### Parameters
#### Request Body
- **options** (PasskeySignupOptions) - Required - `PasskeySignupChallengeOptions & { scope?: string; audience?: string }`
  - **email** (string) - Required - User's email address
  - **audience** (string) - Optional - API audience
  - **scope** (string) - Optional - OAuth scope
  - **realm** (string) - Optional - Realm for token exchange
  - **organization** (string) - Optional - Organization ID

### Request Example
```js
const tokens = await auth0.passkey.signup({
  email: 'user@example.com',
  audience: 'https://api.example.com'
});
```

### Response
#### Success Response (200)
- **id_token** (string) - ID token
- **token_type** (string) - Token type
- **access_token** (string) - Access token
- **refresh_token** (string) - Optional refresh token
- **expires_in** (number) - Expiration time in seconds
- **scope** (string) - Optional scope

#### Response Example
```js
console.log(tokens.access_token);
```

### Error Handling
- **PasskeyError** ('passkey_not_supported') - `window.PublicKeyCredential` missing
- **PasskeyError** ('passkey_cancelled') - `navigator.credentials.create()` returned nothing
- **PasskeyRegisterError** - Challenge request failed
- **GenericError** - Token exchange failed
```

--------------------------------

### getAuthenticationMethods usage

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/my-account-api-client.md

Usage example for getAuthenticationMethods. It retrieves passkey authentication methods and logs each method's key_id and credential_device_type.

```js
const passkeys = await auth0.myAccount.getAuthenticationMethods('passkey');
passkeys.forEach(p => console.log(p.key_id, p.credential_device_type));
```

--------------------------------

### hasSession Usage Example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/anonymous-session-api-client.md

JavaScript example showing how to check if a visitor already has an anonymous identity.

```js
if (auth0.anonymous.hasSession()) {
  // visitor already has an anonymous identity
}
```

--------------------------------

### Revoke default refresh token (example)

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/Auth0Client.html

Revokes the default refresh token. This is the first example in the documentation.

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

--------------------------------

### constructor(options: Auth0ClientOptions)

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client.md

Creates an instance of Auth0Client with the provided options. Validates configuration, merges defaults, and initializes sub-clients and internal components.

```APIDOC
## constructor(options: Auth0ClientOptions)

### Description
Creates an instance of Auth0Client with the provided options. Validates configuration, merges defaults, and initializes sub-clients and internal components.

### Method
constructor

### Parameters
- **options** (Auth0ClientOptions) - Required - Client configuration; full table in configuration.md

### Behavior
- Validates online-mode config; warns on contradictory Enterprise Connect config.
- Merges authorizationParams with defaults: { scope: 'openid profile email' }, useRefreshTokensFallback: false, useFormData: true, refreshTokenMode: 'offline', anonymousSessionsCacheMode: 'localStorage'.
- Validates Web Crypto availability.
- Builds the cache (options.cache, else cacheLocation — default 'memory'), cookie storage, scope table, transaction manager, Dpop (only when useDpop), domain URL and token issuer.
- Instantiates the four sub-clients.
- Starts a Web Worker (TokenWorker) only when useRefreshTokens: true and cacheLocation === 'memory' and no custom cache.

### Throws
- **InvalidConfigurationError** - refreshTokenMode: 'online' with useRefreshTokens !== true ("Set useRefreshTokens: true.") or useDpop !== true ("Set useDpop: true ...")
- **Error** - cacheLocation is not 'memory' / 'localstorage' — Invalid cache location "<x>"
```

--------------------------------

### Create Auth0Client instance

Source: https://github.com/auth0/auth0-spa-js/blob/main/README.md

Create an Auth0Client instance before rendering or initializing your application. You should only have one instance. Use createAuth0Client with async/await or instantiate Auth0Client directly; if you instantiate directly, you must check the session yourself with getTokenSilently().

```js
import { createAuth0Client } from '@auth0/auth0-spa-js';

//with async/await
const auth0 = await createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  clientId: '<AUTH0_CLIENT_ID>',
  authorizationParams: {
    redirect_uri: '<MY_CALLBACK_URL>'
  }
});

//or, you can just instantiate the client on its own
import { Auth0Client } from '@auth0/auth0-spa-js';

const auth0 = new Auth0Client({
  domain: '<AUTH0_DOMAIN>',
  clientId: '<AUTH0_CLIENT_ID>',
  authorizationParams: {
    redirect_uri: '<MY_CALLBACK_URL>'
  }
});

//if you do this, you'll need to check the session yourself
try {
  await auth0.getTokenSilently();
} catch (error) {
  if (error.error !== 'login_required') {
    throw error;
  }
}
```

--------------------------------

### SMS enrollment example

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/MfaApiClient.html

Enrolls a new SMS authenticator using the mfa.enroll method. Requires mfaToken, factorType 'sms', and phoneNumber.

```typescript
const enrollment = await mfa.enroll({  mfaToken: mfaToken,  factorType: 'sms',  phoneNumber: '+12025551234'});
```

--------------------------------

### Creating a CacheKey and converting to key string

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/cache.md

Demonstrates creating a CacheKey and converting it to a string key. The output shows the key format with the prefix, clientId, audience, and scope joined by '::'.

```js
const key = new CacheKey({ clientId: 'app', audience: 'https://api.example.com', scope: 'openid profile' });
const stored = key.toKey();
// '@@auth0spajs@@::app::https://api.example.com::openid profile'
```

--------------------------------

### signup(options)

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/PasskeyApiClient.html

Registers a new user with a passkey. This is a full flow that handles challenge, WebAuthn, and token exchange in a single call.

```APIDOC
## signup(options)

### Description
Registers a new user with a passkey. This is a full flow that handles challenge, WebAuthn, and token exchange in a single call.

### Method
signup

### Parameters
- **options** (object) - Required - Options for signup, including `email`.

### Request Example
```javascript
const tokens = await auth0.passkey.signup({ email: 'user@example.com' });
```

### Response
Returns a promise that resolves to tokens (e.g., `tokens`).
```

--------------------------------

### getIdTokenClaims guard example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client-session.md

Usage example for getIdTokenClaims as a guard for unauthenticated state. If claims are undefined, redirects to login.

```js
// Guard for unauthenticated state
const claims = await auth0.getIdTokenClaims();
if (!claims) {
  await auth0.loginWithRedirect();
}
```

--------------------------------

### Signup with Passkey

Source: https://github.com/auth0/auth0-spa-js/blob/main/examples/passkeys.md

Register a new user with a passkey. The SDK handles the entire flow internally: requesting a challenge from Auth0, triggering the browser's WebAuthn credential creation ceremony, serializing the result, and exchanging it for tokens. After signup, the user is logged in and getUser() works immediately.

```javascript
import { createAuth0Client } from '@auth0/auth0-spa-js';

const auth0 = await createAuth0Client({
  domain: '<AUTH0_DOMAIN>',
  clientId: '<AUTH0_CLIENT_ID>',
  useRefreshTokens: true, // Required for passkey-based sessions
  authorizationParams: {
    redirect_uri: '<MY_CALLBACK_URL>'
  }
});

// One call handles everything — the user sees the biometric prompt
const tokens = await auth0.passkey.signup({
  email: 'user@example.com',
  name: 'Jane Doe' // optional display name
});

// User is now logged in — getUser() works immediately
const user = await auth0.getUser();
console.log('Signed up:', user);
```

--------------------------------

### actor_token example

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/types/CustomTokenExchangeOptions.html

Example of an actor token used for delegation or impersonation scenarios, such as an AI agent acting on behalf of a user.

```text
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Build the SDK with npm run build

Source: https://github.com/auth0/auth0-spa-js/blob/main/DEVELOPMENT.md

Compiles all JavaScript assets into output modules using Rollup.

```bash
npm run build
```

--------------------------------

### signup(options): Promise<TokenEndpointResponse>

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/PasskeyApiClient.html

Registers a new user with a passkey. Handles the full flow: requests a signup challenge, triggers the browser WebAuthn credential creation ceremony, serializes the result, and exchanges it for tokens.

```APIDOC
## signup(options): Promise<TokenEndpointResponse>

### Description
Registers a new user with a passkey. Handles the full flow: requests a signup challenge, triggers the browser WebAuthn credential creation ceremony, serializes the result, and exchanges it for tokens.

### Method
SDK Method

### Endpoint
PasskeyApiClient.signup

### Parameters
- **options** (PasskeySignupOptions) - Required - Passkey signup options (user identifier, optional scope/audience)

### Returns
Promise<TokenEndpointResponse> - A promise that resolves to the token endpoint response containing access/ID tokens

### Throws
- If WebAuthn is not supported in the browser
- If the challenge request fails
- If the token exchange fails
- If the user cancels the WebAuthn prompt
```

--------------------------------

### Using a cache implementation

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/cache.md

Shows how to use a cache implementation (e.g., LocalStorageCache) to set and get a token entry. The key format includes the client ID and 'default' for audience/scope.

```js
const cache = new LocalStorageCache();
await cache.set('@@auth0spajs@@::myapp::default', { body: {...}, expiresAt: 12345 });
const entry = await cache.get('@@auth0spajs@@::myapp::default');
```

--------------------------------

### actor_token_type example

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/types/CustomTokenExchangeOptions.html

Example of an actor token type identifier. Must be a URI under your organization's control, following the same rules as subject_token_type.

```text
"https://idp.example.com/token-type/agent"
```

--------------------------------

### Custom parameters example

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/types/CustomTokenExchangeOptions.html

Example of additional custom parameters for Auth0 Action processing. Accessible in Action code via event.request.body.

```json
{  custom_parameter: "session_context",  device_fingerprint: "a3d8f7...",}
```

--------------------------------

### POST /me/v1/authentication-methods

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/endpoints.md

Creates a new authentication method enrollment. Requires the create:me:authentication_methods scope.

```APIDOC
## POST /me/v1/authentication-methods

### Description
Creates a new authentication method enrollment. Requires the `create:me:authentication_methods` scope.

### Method
POST

### Endpoint
/me/v1/authentication-methods

### Scope
`create:me:authentication_methods`

### Request Body
`EnrollmentChallengeOptions`

### Success Response
`EnrollmentChallengeResponse`; `id`/`location` parsed from the `Location` response header.

### Error Response
`MyAccountApiError`
```

--------------------------------

### constructor

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/MyAccountApiClient.html

Initializes a new instance of the MyAccountApiClient class.

```APIDOC
## constructor

### Description
Initializes a new instance of the MyAccountApiClient class.

### Parameters
- **options** (object) - Required - Configuration options for the client.

### Returns
A new MyAccountApiClient instance.
```

--------------------------------

### Usage of DPoP helpers

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client-advanced.md

Shows how to use getDpopNonce and generateDpopProof to create a DPoP proof and send it in a fetch request. Requires useDpop: true at construction.

```js
if (auth0.getDpopNonce) {
  const nonce = await auth0.getDpopNonce();
  const proof = await auth0.generateDpopProof({
    url: 'https://api.example.com/data',
    method: 'GET',
    nonce,
    accessToken: await auth0.getTokenSilently()
  });
  const res = await fetch('https://api.example.com/data', {
    headers: { authorization: `DPoP ${await auth0.getTokenSilently()}`, dpop: proof }
  });
}
```

--------------------------------

### Usage example: handling session_expired error

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/anonymous-session-api-client.md

JavaScript example showing how to catch the session_expired error and create a new session with metadata.

```js
try {
  await auth0.anonymous.getTokenSilently({ audience: 'https://api.example.com' });
} catch (e) {
  if (e instanceof AnonymousSessionError && e.code === 'session_expired') {
    await auth0.anonymous.createSession({ metadata: { plan: 'free_trial' } });
  }
}
```

--------------------------------

### Handle connect-account callback distinctly

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client.md

Usage example for handling a connect-account callback. It checks the response_type to detect a connect-account flow and logs the connection and id.

```js
// Handle a connect-account callback distinctly
const result = await auth0.handleRedirectCallback();
if (result.response_type === ResponseType.ConnectCode) {
  console.log('Connected account:', result.connection, result.id);
}
```

--------------------------------

### Retrieve SDK configuration with getConfiguration()

Source: https://github.com/auth0/auth0-spa-js/blob/main/examples/sdk-configuration.md

Initializes the Auth0Client with domain and clientId, then retrieves the SDK configuration using getConfiguration(). Useful for displaying the domain, logging configuration, passing it to other services, or verifying the SDK setup.

```javascript
import { createAuth0Client } from '@auth0/auth0-spa-js';

const auth0 = await createAuth0Client({
  domain: 'YOUR_DOMAIN',
  clientId: 'YOUR_CLIENT_ID'
});

// Get configuration
const config = auth0.getConfiguration();
console.log(config.domain, config.clientId);
```

--------------------------------

### getEnrollmentFactors usage example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/mfa-api-client.md

JavaScript example calling auth0.mfa.getEnrollmentFactors with an mfaToken. If factors exist, the user must enroll; otherwise proceed to challenge.

```js
const factors = await auth0.mfa.getEnrollmentFactors(mfaToken);
if (factors.length > 0) {
  renderEnrollmentOptions(factors); // user must enroll
} else {
  proceedToChallenge();
}
```

--------------------------------

### Release and publish commands for auth0-spa-js

Source: https://github.com/auth0/auth0-spa-js/blob/main/references/commands.md

Commands for prepacking and publishing to CDN. These are for reference only; releases are cut via dedicated release tooling.

```bash
npm run prepack          # runs the production build before packing
npm run publish:cdn      # ccu --trace — CDN publish
```

--------------------------------

### handleRedirectCallback callback side example

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/auth0-client-advanced.md

Example of handling the redirect callback after connectAccountWithRedirect. Checks if the response type is ConnectCode and logs the linked account.

```javascript
// Callback side
const result = await auth0.handleRedirectCallback();
if (result.response_type === ResponseType.ConnectCode) {
  console.log('Linked', result.connection, 'account id', result.id);
}
```

--------------------------------

### Get anonymous access tokens for multiple audiences

Source: https://github.com/auth0/auth0-spa-js/blob/main/examples/anonymous-sessions.md

Each (audience, scope) combination gets its own access token. All tokens share the same anonymous identity.

```javascript
const { accessToken: tokenA } = await auth0.anonymous.getTokenSilently({
  audience: 'https://api-a.example.com'
});

const { accessToken: tokenB } = await auth0.anonymous.getTokenSilently({
  audience: 'https://api-b.example.com'
});
```

--------------------------------

### getSignupChallenge

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/passkey-api-client.md

Requests a signup challenge for passkey registration. This is the first step of the granular two-step flow.

```APIDOC
## [POST] /passkey/getSignupChallenge

### Description
Requests a signup challenge for passkey registration. This is the first step of the granular two-step flow.

### Method
POST

### Endpoint
`auth0.passkey.getSignupChallenge(options)`

### Parameters
#### Request Body
- **options** (PasskeySignupChallengeOptions) - Required - Options for the signup challenge
  - **email** (string) - Required - User's email address

### Request Example
```js
const challenge = await auth0.passkey.getSignupChallenge({
  email: 'user@example.com'
});
```

### Response
#### Success Response (200)
- **challenge** (object) - The signup challenge data

#### Response Example
```js
console.log(challenge);
```

### Error Handling
- **PasskeyRegisterError** - Challenge request failed
```

--------------------------------

### constructor

Source: https://github.com/auth0/auth0-spa-js/blob/main/_autodocs/api-reference/my-account-api-client.md

Creates a new MyAccountApiClient instance with a fetcher and API base URL. Typically only the Auth0Client constructor uses it.

```APIDOC
## constructor

### Description
Creates a new MyAccountApiClient instance with a fetcher and API base URL. Typically only the Auth0Client constructor uses it.

### Method
constructor

### Endpoint
N/A

### Parameters
#### Constructor Parameters
- **myAccountFetcher** (Fetcher<Response>) - Required - The fetcher used for API requests.
- **apiBase** (string) - Required - The base URL for the My Account API.

### Request Example
```ts
new MyAccountApiClient(myAccountFetcher, apiBase)
```

### Response
#### Success Response
No return value.

#### Response Example
N/A
```

--------------------------------

### customTokenExchange: Example with subject and actor tokens

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/Auth0Client.html

Example of calling customTokenExchange with subject and actor tokens. The returned tokenResponse.access_token can be used for downstream APIs while the current user session remains unchanged.

```typescript
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
```

--------------------------------

### getUser

Source: https://github.com/auth0/auth0-spa-js/blob/main/docs/classes/Auth0Client.html

Gets the user profile.

```APIDOC
## getUser

### Description
Gets the user profile.

### Method
method

### Returns
- **Promise** - Resolves with the user profile.
```
Tokens:
Raw