Auth0 Spa Js Skill

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:

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

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

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

Auth0 SPA JS — API Reference & Testing

---

Configuration Reference

Auth0ClientOptions

Options passed to createAuth0Client() or new Auth0Client().

getTokenSilently Options

---

Environment Variables

Vite access:

import.meta.env.VITE_AUTH0_DOMAIN

CRA access:

process.env.REACT_APP_AUTH0_DOMAIN

---

Error Types

---

Claims Reference

Claims available from auth0.getUser() (ID token):

Claims on the access token (from getTokenSilently({ detailedResponse: true })):

---

Testing Checklist

Core Authentication

• [ ] Login redirect sends user to Auth0 Universal Login page
• [ ] After login, user is returned to app (no dangling code= params in URL)
• [ ] auth0.isAuthenticated() returns true after successful login
• [ ] auth0.getUser() returns profile with sub, name, email
• [ ] Logout clears session and redirects to returnTo URL
• [ ] After logout, isAuthenticated() returns false

Token Management

• [ ] getTokenSilently() returns a JWT string
• [ ] Access token decoded at jwt.io shows correct aud, iss, sub
• [ ] Tokens are not stored in localStorage (DevTools → Application → Local Storage)
• [ ] Page refresh maintains authentication (silent auth via checkSession)
• [ ] getTokenSilently() works without redirecting when session is active

Error Handling

• [ ] Navigating to app when not logged in does not throw uncaught errors
• [ ] login_required error on getTokenSilently triggers re-authentication
• [ ] Network failure in getTokenSilently is caught and handled gracefully

Security

• [ ] Auth0 Dashboard: Application type is Single Page Application
• [ ] Auth0 Dashboard: Token Endpoint Auth Method is None
• [ ] Auth0 Dashboard: Allowed Web Origins includes your app origin
• [ ] No client_secret anywhere in source code or .env
• [ ] Dev .env file is in .gitignore

---

Common Issues

---

Security Considerations

Token Storage

Recommendation: Use useRefreshTokens: true with cacheLocation: 'memory' (the default) for the best balance of security and user experience.

No Client Secret

SPAs run entirely in the browser and cannot protect secrets. The Auth0 SPA application type explicitly disables client secret authentication. Never add client_secret to a browser-based application.

PKCE Flow

@auth0/auth0-spa-js always uses the Authorization Code + PKCE (Proof Key for Code Exchange) flow. This protects against authorization code interception and is the only secure OAuth 2.0 flow for browser-based applications.

Content Security Policy

If you need to restrict iframe origins (only relevant when NOT using useRefreshTokens):

Content-Security-Policy: frame-src https://your-tenant.auth0.com;

XSS Protection

Never use cacheLocation: 'localstorage' in production unless you have fully mitigated all XSS risks. XSS can steal tokens from localStorage. The default in-memory cache is immune to XSS-based token theft.

Auth0 SPA JS Integration Patterns

---

Client Initialization

Using createAuth0Client (Recommended)

createAuth0Client initializes the client and automatically calls checkSession() to restore any existing session:

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
  }
});

Using Auth0Client Directly

Use when you need more control over initialization order:

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

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

// Manually check existing session
try {
  await auth0.getTokenSilently();
} catch (error) {
  if (error.error !== 'login_required') {
    throw error;
  }
}

---

Login

Login with Redirect

// Basic redirect login
await auth0.loginWithRedirect();

// With additional parameters
await auth0.loginWithRedirect({
  authorizationParams: {
    audience: 'https://api.example.com',
    scope: 'openid profile email read:data'
  }
});

Handle Redirect Callback

Call this on page load to process the redirect result after Auth0 returns the user:

const query = new URLSearchParams(window.location.search);
if ((query.has('code') || query.has('error')) && query.has('state')) {
  try {
    const result = await auth0.handleRedirectCallback();
    // result.appState contains data you passed via loginWithRedirect
    console.log('App state:', result.appState);
  } catch (err) {
    console.error('Redirect callback failed:', err);
  }
  // Clean up URL after processing
  window.history.replaceState({}, document.title, window.location.pathname);
}

Login with Popup

Use when you want to avoid a full-page redirect (must be triggered directly by a user click):

document.getElementById('login-popup-btn').addEventListener('click', async () => {
  try {
    await auth0.loginWithPopup();
    const user = await auth0.getUser();
    console.log('Logged in:', user.name);
  } catch (err) {
    if (err.error !== 'popup_cancelled') {
      console.error('Popup login failed:', err);
    }
  }
});

---

Logout

// Logout and return to app origin
auth0.logout({
  logoutParams: {
    returnTo: window.location.origin
  }
});

// Logout without redirect (clear local session only)
auth0.logout({ openUrl: false });

// Logout and redirect to custom URL
auth0.logout({
  logoutParams: {
    returnTo: 'https://your-app.example.com/logged-out'
  }
});

---

User Profile

// Check authentication state
const isAuthenticated = await auth0.isAuthenticated();

// Get user profile (returns undefined if not authenticated)
const user = await auth0.getUser();
if (user) {
  console.log(user.sub);       // Auth0 user ID
  console.log(user.name);      // Full name
  console.log(user.email);     // Email address
  console.log(user.picture);   // Profile picture URL
  console.log(user.email_verified); // Boolean
}

---

Protecting Content

Show/hide content based on authentication state:

async function updateUI() {
  const isAuthenticated = await auth0.isAuthenticated();

  // Toggle login/logout buttons
  document.getElementById('btn-login').style.display = isAuthenticated ? 'none' : 'block';
  document.getElementById('btn-logout').style.display = isAuthenticated ? 'block' : 'none';

  // Show user profile section
  const profileSection = document.getElementById('profile');
  if (profileSection) {
    profileSection.style.display = isAuthenticated ? 'block' : 'none';
  }

  if (isAuthenticated) {
    const user = await auth0.getUser();
    document.getElementById('user-name').textContent = user.name;
    document.getElementById('user-email').textContent = user.email;
    if (document.getElementById('user-picture')) {
      document.getElementById('user-picture').src = user.picture;
    }
  }
}

// Call on page load and after auth state changes
await updateUI();

---

Calling Protected APIs

// Get access token silently (uses cache first, refreshes if expired)
async function callApi(url) {
  const accessToken = await auth0.getTokenSilently();

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${accessToken}`
    }
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

// Usage
document.getElementById('call-api-btn').addEventListener('click', async () => {
  try {
    const data = await callApi('https://your-api.example.com/private');
    document.getElementById('result').textContent = JSON.stringify(data, null, 2);
  } catch (err) {
    console.error('API call failed:', err);
  }
});

Get Detailed Token Response

const { access_token, token_type, id_token, expires_in } = await auth0.getTokenSilently({
  detailedResponse: true
});

Token for a Specific Audience

const token = await auth0.getTokenSilently({
  authorizationParams: {
    audience: 'https://api.example.com',
    scope: 'read:data write:data'
  }
});

---

Refresh Token Rotation

Enable to maintain sessions across page refreshes without relying on third-party cookies (recommended for modern browsers):

const auth0 = await createAuth0Client({
  domain: import.meta.env.VITE_AUTH0_DOMAIN,
  clientId: import.meta.env.VITE_AUTH0_CLIENT_ID,
  useRefreshTokens: true,
  authorizationParams: {
    redirect_uri: window.location.origin,
    scope: 'openid profile email offline_access'  // offline_access required
  }
});

Note: Enable Allow Offline Access on your Auth0 API in the Dashboard for offline_access scope to work.

---

Organizations

Login to a Specific Organization

await auth0.loginWithRedirect({
  authorizationParams: {
    organization: 'org_xxxxxxxxxxxx'  // or organization name
  }
});

Initialize Client with Organization

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,
    organization: 'org_xxxxxxxxxxxx'
  }
});

Switch Organizations

async function switchOrganization(orgId) {
  await auth0.logout({ openUrl: false });
  await auth0.loginWithRedirect({
    authorizationParams: { organization: orgId }
  });
}

Accept User Invitations

const url = new URL(window.location.href);
const organization = url.searchParams.get('organization');
const invitation = url.searchParams.get('invitation');

if (organization && invitation) {
  await auth0.loginWithRedirect({
    authorizationParams: { organization, invitation }
  });
}

---

MFA Handling

Handle MFA when getTokenSilently() requires a second factor:

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

try {
  const token = await auth0.getTokenSilently();
} catch (error) {
  if (error instanceof MfaRequiredError) {
    // Trigger MFA challenge via popup or redirect
    await auth0.loginWithPopup({
      authorizationParams: {
        mfa_token: error.mfa_token
      }
    });
  }
}

---

DPoP (Device-Bound Tokens)

Enable DPoP to bind access tokens to the client's cryptographic key pair:

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

// Use createFetcher to automatically handle DPoP proof generation
const fetcher = auth0.createFetcher({ dpopNonceId: 'my_api' });

const response = await fetcher.fetchWithAuth('https://api.example.com/data', {
  method: 'GET'
});

---

Error Handling

import {
  AuthenticationError,
  GenericError,
  TimeoutError,
  PopupTimeoutError,
  PopupCancelledError,
  PopupOpenError,
  MfaRequiredError,
  MissingRefreshTokenError
} from '@auth0/auth0-spa-js';

// Handle redirect callback errors
try {
  await auth0.handleRedirectCallback();
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Auth0 returned an error in the callback (e.g., access_denied)
    console.error('Auth error:', err.error, err.error_description);
  } else {
    console.error('Unexpected error:', err);
  }
}

// Handle token errors
try {
  const token = await auth0.getTokenSilently();
} catch (err) {
  if (err.error === 'login_required') {
    // User needs to log in — redirect to login
    await auth0.loginWithRedirect();
  } else if (err instanceof MissingRefreshTokenError) {
    // Refresh token missing — user needs to re-authenticate
    await auth0.loginWithRedirect();
  } else if (err instanceof TimeoutError) {
    console.error('Request timed out');
  } else {
    console.error('Token error:', err);
  }
}

// Handle popup errors
try {
  await auth0.loginWithPopup();
} catch (err) {
  if (err instanceof PopupOpenError) {
    console.error('Popups are blocked. Please allow popups for this site.');
  } else if (err instanceof PopupCancelledError) {
    console.log('User closed the popup');
  } else if (err instanceof PopupTimeoutError) {
    console.error('Popup timed out');
  }
}

---

Authentication Flow

User clicks Login
      ↓
auth0.loginWithRedirect()
      ↓
Browser redirects to Auth0 Universal Login
      ↓
User enters credentials / social login
      ↓
Auth0 redirects back to redirect_uri?code=xxx&state=xxx
      ↓
auth0.handleRedirectCallback() — exchanges code for tokens
      ↓
Tokens stored in memory (or refresh token if useRefreshTokens: true)
      ↓
auth0.isAuthenticated() → true
auth0.getUser() → user profile
auth0.getTokenSilently() → access token

---

Testing Patterns

Test Authentication State

describe('Auth0 integration', () => {
  it('should show login button when not authenticated', async () => {
    const isAuthenticated = await auth0.isAuthenticated();
    expect(isAuthenticated).toBe(false);
    expect(document.getElementById('btn-login').style.display).toBe('block');
  });
});

Mock Auth0 Client in Tests

// Vitest / Jest
vi.mock('@auth0/auth0-spa-js', () => ({
  createAuth0Client: vi.fn().mockResolvedValue({
    isAuthenticated: vi.fn().mockResolvedValue(true),
    getUser: vi.fn().mockResolvedValue({ name: 'Test User', email: 'test@example.com' }),
    loginWithRedirect: vi.fn(),
    logout: vi.fn(),
    getTokenSilently: vi.fn().mockResolvedValue('mock-access-token'),
    handleRedirectCallback: vi.fn().mockResolvedValue({ appState: null })
  })
}));

Auth0 SPA JS Setup Guide

Complete setup instructions with automated scripts and manual configuration options.

---

Quick Setup (Automated)

Never read the contents of `.env` at any point during setup. The file may contain sensitive secrets that should not be exposed in the LLM context. If you determine you need to read the file for any reason, ask the user for explicit permission before doing so — do not proceed until the user confirms.

Before running any part of this setup that writes to `.env`, you MUST ask the user for explicit confirmation. Follow the steps below precisely.

Step 1: Check for existing .env and confirm with user

Before writing to .env, check whether the file already exists:

test -f .env && echo "EXISTS" || echo "NOT_FOUND"

Then ask the user for explicit confirmation before proceeding — do not continue until the user confirms:

• If .env does not exist, ask:
• Question: "This setup will create a .env file containing Auth0 credentials (domain and client ID). Do you want to proceed?"
• Options: "Yes, create .env" / "No, I'll configure it manually"

• If .env already exists, ask:
• Question: "A .env file already exists and may contain secrets unrelated to Auth0. This setup will append Auth0 credentials to it without modifying existing content. Do you want to proceed?"
• Options: "Yes, append to existing .env" / "No, I'll update it manually"

Do not proceed with writing to `.env` unless the user selects the confirmation option.

Step 2: Run automated setup (only after confirmation)

Bash Script (macOS/Linux)

#!/bin/bash

# Install Auth0 CLI if needed
if ! command -v auth0 &> /dev/null; then
  echo "Installing Auth0 CLI..."
  if [[ "$OSTYPE" == "darwin"* ]]; then
    brew install auth0/auth0-cli/auth0
  elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
    curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh -s -- -b /usr/local/bin
  else
    echo "Please install Auth0 CLI: https://github.com/auth0/auth0-cli#installation"
    exit 1
  fi
fi

# Check if logged in to Auth0
if ! auth0 tenants list &> /dev/null; then
  echo ""
  echo "======================================"
  echo "Auth0 Login Required"
  echo "======================================"
  read -p "Do you have an Auth0 account? (y/n): " HAS_ACCOUNT

  if [[ "$HAS_ACCOUNT" != "y" ]]; then
    echo ""
    echo "Create a free account at: https://auth0.com/signup"
    read -p "Press Enter when you've created your account..."
  fi

  auth0 login
  if ! auth0 tenants list &> /dev/null; then
    echo "❌ Login failed. Please try again."
    exit 1
  fi
  echo "✅ Successfully logged in to Auth0!"
fi

# Detect env var prefix from project
if grep -q '"vite"' package.json 2>/dev/null; then
  PREFIX="VITE_AUTH0"
elif grep -q '"react-scripts"' package.json 2>/dev/null; then
  PREFIX="REACT_APP_AUTH0"
else
  PREFIX="VITE_AUTH0"  # Default to Vite
fi

# List apps and prompt for selection
echo "Your Auth0 applications:"
auth0 apps list

read -p "Enter your Auth0 app ID (or press Enter to create a new one): " APP_ID

if [ -z "$APP_ID" ]; then
  echo "Creating new Auth0 SPA application..."
  APP_NAME="${PWD##*/}-spa"
  APP_ID=$(auth0 apps create \
    --name "$APP_NAME" \
    --type spa \
    --auth-method None \
    --callbacks "http://localhost:3000,http://localhost:5173" \
    --logout-urls "http://localhost:3000,http://localhost:5173" \
    --origins "http://localhost:3000,http://localhost:5173" \
    --web-origins "http://localhost:3000,http://localhost:5173" \
    --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
  echo "Created SPA app with ID: $APP_ID"
fi

# Get app details
AUTH0_DOMAIN=$(auth0 apps show "$APP_ID" --json | grep -o '"domain":"[^"]*' | cut -d'"' -f4)
AUTH0_CLIENT_ID=$(auth0 apps show "$APP_ID" --json | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)

# Append to .env
cat >> .env << EOF
${PREFIX}_DOMAIN=$AUTH0_DOMAIN
${PREFIX}_CLIENT_ID=$AUTH0_CLIENT_ID
EOF

echo "✅ Auth0 configuration complete!"
echo "Appended to .env:"
echo "  ${PREFIX}_DOMAIN=$AUTH0_DOMAIN"
echo "  ${PREFIX}_CLIENT_ID=$AUTH0_CLIENT_ID"

PowerShell Script (Windows)

# Install Auth0 CLI if not present
if (!(Get-Command auth0 -ErrorAction SilentlyContinue)) {
  Write-Host "Installing Auth0 CLI..."
  scoop install auth0
}

# Check if logged in
try {
  auth0 tenants list | Out-Null
} catch {
  Write-Host "Auth0 Login Required"
  $hasAccount = Read-Host "Do you have an Auth0 account? (y/n)"

  if ($hasAccount -ne "y") {
    Write-Host "Create a free account at: https://auth0.com/signup"
    Read-Host "Press Enter when you've created your account"
  }

  auth0 login
  Write-Host "✅ Successfully logged in to Auth0!"
}

# Detect env var prefix
$prefix = if (Select-String -Path "package.json" -Pattern '"vite"' -Quiet) { "VITE_AUTH0" }
          elseif (Select-String -Path "package.json" -Pattern '"react-scripts"' -Quiet) { "REACT_APP_AUTH0" }
          else { "VITE_AUTH0" }

# List and select app
Write-Host "Your Auth0 applications:"
auth0 apps list

$appId = Read-Host "Enter your Auth0 app ID (or press Enter to create new)"

if ([string]::IsNullOrEmpty($appId)) {
  $appName = Split-Path -Leaf (Get-Location)
  Write-Host "Creating new Auth0 SPA application..."
  $appJson = auth0 apps create --name "$appName-spa" --type spa `
    --auth-method None `
    --callbacks "http://localhost:3000,http://localhost:5173" `
    --logout-urls "http://localhost:3000,http://localhost:5173" `
    --origins "http://localhost:3000,http://localhost:5173" `
    --web-origins "http://localhost:3000,http://localhost:5173" `
    --json

  $appId = ($appJson | ConvertFrom-Json).client_id
  Write-Host "Created app with ID: $appId"
}

# Get credentials
$appDetails = auth0 apps show $appId --json | ConvertFrom-Json

@"
${prefix}_DOMAIN=$($appDetails.domain)
${prefix}_CLIENT_ID=$($appDetails.client_id)
"@ | Out-File -FilePath .env -Encoding UTF8 -Append

Write-Host "✅ Auth0 configuration complete!"
Write-Host "  ${prefix}_DOMAIN=$($appDetails.domain)"
Write-Host "  ${prefix}_CLIENT_ID=$($appDetails.client_id)"

---

Manual Setup

If you prefer manual setup or the scripts don't work:

Step 1: Install SDK

npm install @auth0/auth0-spa-js

Step 2: Install Auth0 CLI

macOS:

brew install auth0/auth0-cli/auth0

Linux:

curl -sSfL https://raw.githubusercontent.com/auth0/auth0-cli/main/install.sh | sh

Windows:

scoop install auth0

Step 3: Get Credentials

# Login to Auth0
auth0 login

# List your apps
auth0 apps list

# Get app details (replace <app-id>)
auth0 apps show <app-id>

Step 4: Create .env File

For Vite-based projects:

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

For Create React App:

REACT_APP_AUTH0_DOMAIN=your-tenant.auth0.com
REACT_APP_AUTH0_CLIENT_ID=your-client-id

For Webpack / plain HTML:

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id

---

Creating an Auth0 Application via Dashboard

1. Go to Auth0 Dashboard 2. Navigate to Applications → Applications 3. Click Create Application 4. Choose:

• Name: Your app name
• Type: Single Page Web Applications

5. Configure in the Settings tab:

• Allowed Callback URLs: http://localhost:5173, http://localhost:3000
• Allowed Logout URLs: http://localhost:5173, http://localhost:3000
• Allowed Web Origins: http://localhost:5173, http://localhost:3000
• Allowed Origins (CORS): http://localhost:5173, http://localhost:3000

6. Click Save Changes 7. Copy your Domain and Client ID

Important: The Allowed Web Origins field is required for getTokenSilently() (silent authentication). Without it, users will be logged out on every page refresh.

---

Secret Management

SPAs do not use a client_secret. The Auth0 SPA application type explicitly sets the Token Endpoint Authentication Method to None. If you see a client secret anywhere in your code, remove it immediately.

Your .env file contains only:

• AUTH0_DOMAIN / VITE_AUTH0_DOMAIN — Not a secret (public)
• AUTH0_CLIENT_ID / VITE_AUTH0_CLIENT_ID — Not a secret (public)

Still, follow these practices:

• Add .env to .gitignore (to avoid accidental commits with other sensitive env vars)
• Use .env.local for Vite projects (auto-ignored by Vite's default .gitignore)
• Never commit credential files to version control

---

Troubleshooting Setup

Environment Variables Not Loading

Vite:

• Ensure variables start with VITE_
• Restart the dev server after creating/editing .env
• Use import.meta.env.VITE_AUTH0_DOMAIN (not process.env)

Create React App:

• Ensure variables start with REACT_APP_
• Restart dev server after changes

Auth0 CLI Issues

Browser doesn't open for login:

auth0 login --no-browser

"Not logged in" error:

auth0 login --force

---

Next Steps

After setup is complete: 1. Return to main skill guide for integration steps 2. See Integration Guide for advanced patterns 3. Check API Reference for complete SDK documentation

Agent System

You are a software developer adding Auth0 authentication to a Vanilla JS single-page application. You have access to tools for reading/writing files, running commands, and fetching URLs. Use these tools to complete the integration task below.

Task

Add Auth0 authentication to a Vanilla JS application using the @auth0/auth0-spa-js SDK.

Auth0 Credentials:

• Domain: dev-example.auth0.com
• Client ID: abc123def456ghi789jkl012