Customization & Response Mapping

How to connect non-standard APIs, customize cookies, response paths, and custom middleware.

Reference & Recipes Nuxt 3.12+ / Nuxt 4 / TypeScript

Configuring Response Paths

Different backend frameworks structure JSON responses differently. Rather than forcing you to modify your backend, nuxt-bearer-auth provides a flexible path evaluator.

Example: Fastify / NestJS Custom JSON Response

Suppose your backend returns:

json

{
  "statusCode": 200,
  "result": {
    "jwt": "eyJhbGciOiJIUz...",
    "refreshJwt": "def987...",
    "account": {
      "uuid": "usr_99182",
      "emailAddress": "alex@example.com",
      "fullName": "Alex Rivera"
    }
  }
}

Map this in nuxt.config.ts:

typescript

export default defineNuxtConfig({
  modules: ['nuxt-bearer-auth'],

  bearerAuth: {
    apiBaseUrl: process.env.API_BASE_URL,
    responsePaths: {
      token: ['result.jwt'],
      refreshToken: ['result.refreshJwt'],
      user: ['result.account'],
      userId: ['uuid', 'result.account.uuid'],
      success: ['statusCode'],
    },
  },
})

Custom Endpoint Mappings

If your backend uses a non-standard URL structure (e.g. /v2/auth/token instead of /auth/login):

typescript

export default defineNuxtConfig({
  bearerAuth: {
    endpoints: {
      login: 'v2/auth/token',
      logout: 'v2/auth/sign-out',
      me: 'v2/users/self',
      refresh: 'v2/auth/token-refresh',
      register: 'v2/onboarding/create-account',
    },
  },
})

Custom Cookie Configurations

You can customize the session cookie name, domain (for sharing sessions across subdomains), and security flags:

typescript

bearerAuth: {
  sessionCookie: {
    name: '__Host-app_session',
    devName: 'app_session_dev',
    domain: "production" === 'production' ? '.example.com' : undefined,
    maxAge: 60 * 60 * 24 * 30, // 30 days
    sameSite: 'lax',
  },
}

Note: The HttpOnly flag is always true on the session cookie and is not configurable. The Secure flag defaults to true in production and can be overridden via sessionCookie.secure.

Custom Route Middleware

If you want to handle route protection entirely in your own middleware (for example to check user roles from auth.user.value), you can disable the built-in global middleware:

typescript

bearerAuth: {
  routes: {
    middleware: false, // Disables the built-in global route middleware
  },
}

Then create your own middleware/auth.global.ts. The example below shows a user-implemented pattern that checks a role property on the user object — this logic is entirely in your application code, not provided by nuxt-bearer-auth:

typescript

// middleware/auth.global.ts
export default defineNuxtRouteMiddleware((to) => {
  const auth = useBearerAuth()

  if (!auth.isAuthenticated.value && to.path.startsWith('/admin')) {
    return navigateTo('/login')
  }

  // Role checking is application logic — implement it here based on
  // whatever your auth.user.value shape looks like
  if (to.meta.role && auth.user.value?.role !== to.meta.role) {
    return navigateTo('/forbidden')
  }
})

API & Composable Reference

Cookbook & Integration Examples