Configuration Reference
Comprehensive guide to all configuration options available in nuxt-bearer-auth.
Overview & Getting Started Nuxt 4 / TypeScript
Module Options Overview
All module options are defined under thebearerAuth key in your nuxt.config.ts.Here is a full configuration snippet with all available options and their default values:
typescript
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['nuxt-bearer-auth'],
bearerAuth: {
// 1. Core connection settings
apiBaseUrl: process.env.API_BASE_URL || '',
redisUrl: process.env.REDIS_URL || 'redis://127.0.0.1:6379',
sessionSecret: process.env.SESSION_SECRET || '',
appEnv: process.env.APP_ENV || "production" || 'development',
installCsurf: true,
// 2. External API Endpoints
endpoints: {
login: 'auth/login',
socialLogin: 'auth/social-login',
logout: 'auth/logout',
me: 'auth/account/me',
refresh: 'auth/refresh',
forgotPassword: 'auth/forgot-password',
resetPassword: 'auth/reset-password',
verifyOtp: 'auth/verify-otp',
resendOtp: 'auth/resend-otp/:identifier',
register: 'auth/register',
},
// 3. Response Shape Normalization
responsePaths: {
token: ['data.token', 'token', 'access_token', 'data.access_token'],
refreshToken: ['data.refreshToken', 'data.refresh_token', 'refreshToken', 'refresh_token'],
user: ['data.user', 'user', 'data', '$'],
userId: ['id', 'uuid', 'data.id', 'data.uuid'],
message: ['message', 'data.message'],
success: ['success', 'status'],
code: ['code', 'data.code'],
nextAction: ['next_action', 'data.next_action', 'nextAction'],
},
// 4. Client Navigation Redirects
redirects: {
login: '/login',
authenticated: '/dashboard',
logout: '/',
unauthorized: '/auth/not-allowed',
},
// 5. Route Protection & Local API Prefixes
routes: {
localApiPrefix: '/api/auth',
public: ['/', '/login', '/forgot-password', '/reset-password'],
authPages: ['/login', '/forgot-password', '/reset-password'],
protectedApiPrefixes: ['/api'],
publicApiPrefixes: [
'/api/auth/login',
'/api/auth/social-login',
'/api/auth/register',
'/api/auth/forgot-password',
'/api/auth/reset-password',
'/api/auth/otp-verification',
'/api/auth/resend-otp',
'/api/_csrf',
'/_nuxt',
'/__nuxt',
'/_ipx',
'/favicon.ico',
],
middleware: true,
},
// 6. Session Cookie
sessionCookie: {
name: 'nuxt_bearer_auth_session',
devName: 'nuxt_bearer_auth_session_dev',
maxAge: 60 * 60 * 24 * 7, // 7 days in seconds
sameSite: 'lax',
secure: undefined, // Defaults to true in production
domain: undefined, // Optional: set to '.example.com' for subdomain sharing
path: '/',
},
// 7. CSRF Configuration
csrf: {
enabled: true,
https: false,
cookieKey: 'nuxt_bearer_auth_csrf',
devCookieKey: 'nuxt_bearer_auth_csrf_dev',
headerName: 'x-csrf-token',
methods: ['POST', 'PUT', 'PATCH', 'DELETE'],
methodsToProtect: ['POST', 'PUT', 'PATCH', 'DELETE'],
cookie: {
path: '/',
httpOnly: true,
sameSite: 'strict',
},
},
// 8. Next Action Interceptors
verificationRequiredActions: ['verify_account', 'verification_required'],
twoFactorRequiredActions: ['two_factor_required', '2fa_required'],
},
})
Core Connection Options
| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | |apiBaseUrl | string | "" | Base URL of your backend bearer-token API. |
| redisUrl | string | "redis://127.0.0.1:6379" | Redis connection URI. |
| sessionSecret | string | "" | Reserved field for a future session signing or encryption secret. Currently accepted by the module but not used at runtime — sessions are stored as JSON in Redis without additional application-level encryption. See Redis Security Hardening for how to secure Redis at the infrastructure level. |
| appEnv | string | process.env.APP_ENV | Application environment name (local, development, production). Controls dev vs production cookie names and Secure attribute behaviour. |
| installCsurf | boolean | true | Automatically registers nuxt-csurf module. |
Endpoints Configuration
Override any endpoint relative to yourapiBaseUrl:
typescript
bearerAuth: {
endpoints: {
login: 'v1/oauth/token',
me: 'v1/users/current',
logout: 'v1/oauth/revoke',
refresh: 'v1/oauth/refresh',
}
}
Response Paths (Mapping)
The module includes a JSON path evaluator that iterates through key candidates until it finds a valid value. This allows you to connect non-standard API backends without modifying your backend source code.
typescript
bearerAuth: {
responsePaths: {
token: ['payload.token', 'jwt'],
refreshToken: ['payload.refresh_jwt'],
user: ['payload.account', 'user_profile'],
userId: ['user_id', '_id'],
}
}
Session Cookie Options
| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | |name | string | "nuxt_bearer_auth_session" | Production cookie name. |
| devName | string | "nuxt_bearer_auth_session_dev" | Development cookie name (used when appEnv is local or development). |
| maxAge | number | 604800 (7 days) | Session TTL in seconds. Applied to both the Redis key and the browser cookie. The session uses a sliding expiration window — authenticated activity resets this TTL back to the full maxAge value. |
| sameSite | "lax" | "strict" | "none" | "lax" | SameSite attribute for the session cookie. |
| secure | boolean | auto (true in prod) | Requires HTTPS transmission. Automatically true when NODE_ENV=production or appEnv=production. |
| domain | string | undefined | Optional cookie domain. Set to .example.com to share the session across subdomains. |
| path | string | "/" | Cookie path. |
Note: The HttpOnly flag is always set on the session cookie — it is hardcoded and not configurable. This ensures the session identifier can never be read by browser JavaScript.