Auth0 SPA JS Integration#

Add authentication to any browser-based single-page application using @auth0/auth0-spa-js — the low-level Auth0 SDK for Vanilla JS, Svelte, SolidJS, and any SPA not using React, Angular, or Vue.

Agent instruction: Before providing SDK setup instructions, fetch the latest release version by running:

text

gh api repos/auth0/auth0-spa-js/releases/latest --jq '.tag_name'

Use the returned version in all dependency lines instead of any hardcoded version below. If the command fails, fall back to checking https://github.com/auth0/auth0-spa-js/releases.

Prerequisites#

• Modern browser with ES2017+ support
• npm or yarn (or use CDN for no-bundler apps)
• Auth0 account with a Single Page Application configured
• If you don't have Auth0 set up, see auth0-quickstart

When NOT to Use#

• React SPAs (hooks, Auth0Provider): Use auth0-react
• Angular SPAs (AuthModule, AuthGuard): Use auth0-angular
• Vue 3 SPAs (createAuth0, useAuth0): Use auth0-vue
• Next.js (server-side sessions, App Router): Use auth0-nextjs
• Nuxt (server-side SSR): Use auth0-nuxt
• Express server-side web apps: Use auth0-express
• React Native / Expo mobile apps: Use auth0-react-native

Quick Start Workflow#

1. Install SDK#

bash

npm install @auth0/auth0-spa-js

Or via CDN (no bundler). Run this to get the latest version, then use it in your HTML:

bash

VERSION=$(npm view @auth0/auth0-spa-js version)

html

<script src="https://cdn.auth0.com/js/auth0-spa-js/$VERSION/auth0-spa-js.production.js"></script>

2. Configure Auth0#

For automated setup with Auth0 CLI, see Setup Guide for complete scripts.

For manual setup, create .env (Vite):

bash

VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-id

In Auth0 Dashboard, set for your Single Page Application:

• Allowed Callback URLs: http://localhost:5173
• Allowed Logout URLs: http://localhost:5173
• Allowed Web Origins: http://localhost:5173

3. Initialize Auth0 Client#

js

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

const auth0 = await createAuth0Client({
  domain: import.meta.env.VITE_AUTH0_DOMAIN,
  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
  authorizationParams: {
    redirect_uri: window.location.origin
  }
});

// Handle redirect callback after login
const query = new URLSearchParams(window.location.search);
if ((query.has('code') || query.has('error')) && query.has('state')) {
  await auth0.handleRedirectCallback();
  window.history.replaceState({}, document.title, window.location.pathname);
}

4. Add Login / Logout#

Agent instruction: Before adding new UI elements, search the project for existing click handlers for login, logout, sign-in, or sign-out buttons. If existing handlers are found, hook the Auth0 code into them without modifying the existing UI. Only create new buttons if no existing handlers are found.

js

// Login
document.getElementById('login-btn').addEventListener('click', async () => {
  await auth0.loginWithRedirect();
});

// Logout
document.getElementById('logout-btn').addEventListener('click', () => {
  auth0.logout({
    logoutParams: { returnTo: window.location.origin }
  });
});

// Update UI based on auth state
const isAuthenticated = await auth0.isAuthenticated();
if (isAuthenticated) {
  const user = await auth0.getUser();
  console.log(user.name, user.email);
}

5. Get Access Tokens for API Calls#

js

const accessToken = await auth0.getTokenSilently();

const response = await fetch('https://your-api.example.com/data', {
  headers: { Authorization: `Bearer ${accessToken}` }
});

6. Build & Verify#

Agent instruction: After completing the integration, build the project to verify it compiles successfully:

bash

npm run build

If the build fails, analyze the error output and fix the issues. Common integration build failures include:

• Module not found: Missing npm install @auth0/auth0-spa-js — run the install command
• Cannot find name 'import.meta': TypeScript target too low — set "target": "ES2020" or higher in tsconfig.json
• createAuth0Client is not a function: Wrong import path or CDN usage without bundle step
• Env vars undefined at runtime: Vite requires VITE_ prefix; webpack/CRA requires REACT_APP_ prefix

Re-run the build after each fix. Track the number of build-fix iterations.

Failcheck: If the build still fails after 5–6 fix attempts, stop and ask the user using AskUserQuestion: "The build is still failing after several fix attempts. How would you like to proceed?"

• Let the skill continue fixing iteratively — continue the build-fix loop for another 5–6 attempts
• Fix it manually — show the remaining errors and let the user resolve them
• Skip build verification — proceed without a successful build

Detailed Documentation#

• Setup Guide — Automated setup scripts (Bash/PowerShell), Auth0 CLI commands, .env configuration, callback URL setup
• Integration Patterns — Token management, calling APIs, refresh tokens, organizations, MFA, DPoP, error handling, advanced patterns
• Testing & Reference — Configuration options, claims reference, testing checklist, common issues, security considerations

Common Mistakes#

MistakeFixCallback URL port mismatch (e.g., localhost:3001 vs localhost:5173)Match Allowed Callback URLs exactly to your dev server port in Auth0 Dashboardclient_secret in SPA codeSPAs must never have a client secret — remove it. Auth0 sets auth method to None for SPA appsTokens stored in localStorageUse in-memory storage (default) or sessionStorage. Never localStorage — XSS riskgetTokenSilently() throws login_required on page refreshAdd your app origin to Allowed Web Origins in Auth0 DashboardhandleRedirectCallback() not called after redirectMust call after login redirect to exchange the auth code; without this the URL params persist and re-triggerDomain includes https:// prefixAuth0 domain should be hostname only: your-tenant.auth0.com, not https://your-tenant.auth0.com``loginWithPopup() called from async init codePopups must be triggered directly from a user gesture (click handler). Never call from init or page load codeUsing Auth0Provider from @auth0/auth0-react in Vanilla JSFor Vanilla JS, use createAuth0Client() directly — no provider component needed

Related Skills#

• auth0-quickstart — Set up an Auth0 account and application
• auth0-react — Auth0 for React SPAs with hooks
• auth0-angular — Auth0 for Angular SPAs
• auth0-vue — Auth0 for Vue 3 SPAs
• auth0-mfa — Add Multi-Factor Authentication
• auth0-cli — Manage Auth0 resources from the terminal

Quick Reference#

Core Methods#

MethodDescriptioncreateAuth0Client(options)Create and initialize client (calls checkSession internally)new Auth0Client(options)Instantiate without auto session checkauth0.loginWithRedirect(options?)Redirect to Auth0 Universal Loginauth0.loginWithPopup(options?)Open Auth0 login in a popupauth0.logout(options?)Clear session and redirectauth0.handleRedirectCallback(url?)Process redirect result after loginauth0.isAuthenticated()``Promise<boolean>``auth0.getUser()``Promise<User | undefined>``auth0.getTokenSilently(options?)``Promise<string> — access tokenauth0.checkSession()Attempt silent re-authentication

Common Use Cases#

• Login/Logout → See Step 4 above
• Protecting content → Integration Guide
• API calls with tokens → Integration Guide
• Refresh tokens → Integration Guide
• Organizations → Integration Guide
• MFA handling → Integration Guide
• Error handling → Integration Guide

References#

• Auth0 SPA JS SDK Documentation
• Auth0 Vanilla JS Quickstart
• SDK GitHub Repository
• EXAMPLES.md — Advanced patterns
• API Documentation