auth0-nuxt

by auth0

Use when implementing Auth0 authentication in Nuxt 3/4 applications, configuring session management, protecting routes with middleware, or integrating API… npx skills add https://github.com/auth0/agent-skills --skill auth0-nuxt Download ZIPGitHub37

Auth0 Nuxt SDK

Overview

Server-side session authentication for Nuxt 3/4. NOT the same as @auth0/auth0-vue (client-side SPA).

Core principle: Uses server-side encrypted cookie sessions, not client-side tokens.

When to Use

Use this when:

• Building Nuxt 3/4 applications with server-side rendering (Node.js 20 LTS+)

• Need secure session management with encrypted cookies

• Protecting server routes and API endpoints

• Accessing Auth0 Management API or custom APIs

Don't use this when:

• Using Nuxt 2 (not supported - use different Auth0 SDK)

• Building pure client-side SPA without server (use @auth0/auth0-vue instead)

• Using non-Auth0 authentication provider

• Static site generation only (SSG) without server runtime

Critical Mistakes to Avoid

Mistake Solution Installing @auth0/auth0-vue or @auth0/auth0-spa-js Use @auth0/auth0-nuxt Auth0 app type "Single Page Application" Use "Regular Web Application" Env vars: VITE_AUTH0_* or VUE_APP_AUTH0_* Use NUXT_AUTH0_* prefix Using useUser() for security checks Use useAuth0(event).getSession() server-side Missing callback URLs in Auth0 Dashboard Add http://localhost:3000/auth/callback Weak/missing session secret Generate: openssl rand -hex 64 Hardcoding credentials in nuxt.config.ts Leave runtimeConfig values as empty strings; Nuxt auto-fills from NUXT_AUTH0_* env vars

Built-in Routes

The SDK automatically mounts these routes:

Route Method Purpose /auth/login GET Initiates login flow. Supports ?returnTo=/path parameter /auth/callback GET Handles Auth0 callback after login /auth/logout GET Logs user out and redirects to Auth0 logout /auth/backchannel-logout POST Receives logout tokens for back-channel logout

Customize: Pass routes: { login, callback, logout, backchannelLogout } or mountRoutes: false to module config.

Composables

Composable Context Usage useAuth0(event) Server-side Access getUser(), getSession(), getAccessToken(), logout() useUser() Client-side Display user data only. Never use for security checks

// Server example
const auth0 = useAuth0(event);
const session = await auth0.getSession();

 
const user = useUser();
 

 
 Welcome {{ user.name }}

 

Protecting Routes

Three layers: Route middleware (client), server middleware (SSR), API guards.

// middleware/auth.ts - Client navigation
export default defineNuxtRouteMiddleware((to) => {
 if (!useUser().value) return navigateTo(`/auth/login?returnTo=${encodeURIComponent(to.path)}`);
});

// server/middleware/auth.server.ts - SSR protection
export default defineEventHandler(async (event) => {
 const url = getRequestURL(event);
 const auth0Client = useAuth0(event);
 const session = await auth0Client.getSession();
 if (!session) {
 return sendRedirect(event, `/auth/login?returnTo=${encodeURIComponent(url.pathname)}`);
 }
});

// server/api/protected.ts - API endpoint protection
export default defineEventHandler(async (event) => {
 const auth0Client = useAuth0(event);
 const session = await auth0Client.getSession();

 if (!session) {
 throw createError({
 statusCode: 401,
 statusMessage: 'Unauthorized'
 });
 }

 return { data: 'protected data' };
});

For role-based, permission-based, and advanced patterns: route-protection.md

Session Management

Stateless (Default)

Uses encrypted, chunked cookies. No configuration needed.

Stateful (Redis, MongoDB, etc.)

For larger sessions or distributed systems:

// nuxt.config.ts
modules: [
 ['@auth0/auth0-nuxt', {
 sessionStoreFactoryPath: '~/server/utils/session-store-factory.ts'
 }]
]

For complete session store implementations, see: session-stores.md

API Integration

Configure audience for API access tokens:

// nuxt.config.ts
runtimeConfig: {
 auth0: {
 audience: 'https://your-api-identifier',
 }
}

Retrieve tokens server-side:

// server/api/call-api.ts
export default defineEventHandler(async (event) => {
 const auth0Client = useAuth0(event);
 const { accessToken } = await auth0Client.getAccessToken();

 return await $fetch('https://api.example.com/data', {
 headers: {
 Authorization: `Bearer ${accessToken}`
 }
 });
});

Security Checklist

• ✅ Server-side validation only (never trust useUser())

• ✅ HTTPS in production

• ✅ Strong session secret (openssl rand -hex 64)

• ✅ Never commit .env files

• ✅ Stateful sessions for PII/large data

Additional Resources

Guides: Route Protection Patterns • Custom Session Stores • Common Examples

Related Skills

• auth0-quickstart - Basic Auth0 setup

• auth0-cli - Manage Auth0 resources from the terminal

Links: Auth0-Nuxt GitHub • Auth0 Docs • Nuxt Modules