auth0-spa-js

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:

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

npm install @auth0/auth0-spa-js

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

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

<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):

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

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.

// 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

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:

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

Mistake	Fix
Callback URL port mismatch (e.g., localhost:3001 vs localhost:5173)	Match Allowed Callback URLs exactly to your dev server port in Auth0 Dashboard
client_secret in SPA code	SPAs must never have a client secret — remove it. Auth0 sets auth method to None for SPA apps
Tokens stored in localStorage	Use in-memory storage (default) or sessionStorage. Never localStorage — XSS risk
getTokenSilently() throws login_required on page refresh	Add your app origin to Allowed Web Origins in Auth0 Dashboard
handleRedirectCallback() not called after redirect	Must call after login redirect to exchange the auth code; without this the URL params persist and re-trigger
Domain includes https:// prefix	Auth0 domain should be hostname only: your-tenant.auth0.com, not https://your-tenant.auth0.com
loginWithPopup() called from async init code	Popups must be triggered directly from a user gesture (click handler). Never call from init or page load code
Using Auth0Provider from @auth0/auth0-react in Vanilla JS	For 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

Method	Description
createAuth0Client(options)	Create and initialize client (calls checkSession internally)
new Auth0Client(options)	Instantiate without auto session check
auth0.loginWithRedirect(options?)	Redirect to Auth0 Universal Login
auth0.loginWithPopup(options?)	Open Auth0 login in a popup
auth0.logout(options?)	Clear session and redirect
auth0.handleRedirectCallback(url?)	Process redirect result after login
auth0.isAuthenticated()	Promise<boolean>
auth0.getUser()	Promise<User | undefined>
auth0.getTokenSilently(options?)	Promise<string> — access token
auth0.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