npx skills add ...
npx skills add auth0/agent-skills --skill auth0-nuxt
npx skills add auth0/agent-skills --skill auth0-nuxt
Use when adding Auth0 login, logout, session management, or protected routes to a Nuxt 3 or Nuxt 4 application. Integrates @auth0/auth0-nuxt — use even if the user says "add login to my Nuxt app".
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.
Use this when:
Don't use this when:
| 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 |
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.
| Composable | Context | Usage |
|---|---|---|
useAuth0(event) | Server-side | Access getUser(), getSession(), getAccessToken(), logout() |
useUser() | Client-side | Display user data only. Never use for security checks |
Three layers: Route middleware (client), server middleware (SSR), API guards.
For role-based, permission-based, and advanced patterns: route-protection.md
Uses encrypted, chunked cookies. No configuration needed.
For larger sessions or distributed systems:
For complete session store implementations, see: session-stores.md
Configure audience for API access tokens:
Retrieve tokens server-side:
useUser())openssl rand -hex 64).env files| Error | Solution |
|---|---|
| "Module not found" | Install @auth0/auth0-nuxt, not @auth0/auth0-vue |
| "Missing domain/clientId/clientSecret" | Check NUXT_AUTH0_ prefix, .env location, runtimeConfig |
| "Redirect URI mismatch" | Match Auth0 Dashboard callback to appBaseUrl + /auth/callback |
| "useAuth0 is not defined" | Use only in server context with H3 event object |
| Cookies too large | Use stateful sessions or reduce scopes |
Guides: Route Protection Patterns • Custom Session Stores • Common Examples
auth0-quickstart - Basic Auth0 setupauth0-cli - Manage Auth0 resources from the terminalLinks: Auth0-Nuxt GitHub • Auth0 Docs • Nuxt Modules
// 4. nuxt.config.ts
// Leave values as empty strings — Nuxt auto-fills them from NUXT_AUTH0_* env vars at runtime.
// If you prefer explicit mapping, use: domain: process.env.NUXT_AUTH0_DOMAIN || ''
export default defineNuxtConfig({
modules: ['@auth0/auth0-nuxt'],
runtimeConfig: {
auth0: {
domain: '',
clientId: '',
clientSecret: '',
sessionSecret: '',
appBaseUrl: 'http://localhost:3000',
audience: '', // optional
},
},
})// Server example
const auth0 = useAuth0(event);
const session = await auth0.getSession();<script setup>
const user = useUser();
</script>
<template>
<div v-if="user">Welcome {{ user.name }}</div>
<template>// 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' };
});// nuxt.config.ts
modules: [
['@auth0/auth0-nuxt', {
sessionStoreFactoryPath: '~/server/utils/session-store-factory.ts'
}]
]// nuxt.config.ts
runtimeConfig: {
auth0: {
audience: 'https://your-api-identifier',
}
}// 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}`
}
});
});