Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nuxt-alt/auth/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through the most common @nuxt-alt/auth setup: local token authentication, where your own API issues a Bearer token on login and the module stores, attaches, and validates it automatically. By the end you will have a configured strategy, a working login page, a component that reads the authenticated user, and route-level protection — all wired together with the built-in middleware and the useAuth() composable.
1

Install and Configure

If you have not installed the module yet, follow the Installation guide, then add a local strategy to your nuxt.config.ts. The local scheme posts credentials to your login endpoint, reads the token from the response, and calls the user endpoint to hydrate auth.user.
nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt-alt/auth'],
  auth: {
    strategies: {
      local: {
        token: {
          property: 'token',
          type: 'Bearer',
        },
        endpoints: {
          login:  { url: '/api/auth/login',  method: 'post' },
          logout: { url: '/api/auth/logout', method: 'post' },
          user:   { url: '/api/auth/user',   method: 'get'  },
        },
      },
    },
  },
})
  • token.property is the key in your login response JSON that holds the token value (e.g. { "token": "eyJ..." }).
  • token.type is prepended to the token in the Authorization header — Bearer is the standard for most REST APIs.
  • endpoints.user is called automatically after login to populate auth.user.
2

Create a Login Page

Create pages/login.vue. Call auth.loginWith('local', { body: { ... } }) to initiate the login flow. The module posts the body to your configured login endpoint, extracts the token, stores it, then fetches the user profile — all in one call. Use body (not data) because @nuxt-alt/http is built on ofetch.
pages/login.vue
<script setup lang="ts">
const auth = useAuth()
const email = ref('')
const password = ref('')

async function handleLogin() {
  await auth.loginWith('local', {
    body: { email: email.value, password: password.value },
  })
}
</script>

<template>
  <form @submit.prevent="handleLogin">
    <input v-model="email" type="email" placeholder="Email" />
    <input v-model="password" type="password" placeholder="Password" />
    <button type="submit">Sign in</button>
  </form>
</template>
After a successful login, the module redirects the user to the path configured in auth.redirect.home (defaults to /).
3

Access the Authenticated User

useAuth() is auto-imported everywhere in your Nuxt app. Use auth.loggedIn to check authentication status and auth.user to read the profile object returned by your user endpoint. Calling auth.logout() clears all stored tokens and redirects to auth.redirect.logout.
components/NavBar.vue
<script setup lang="ts">
const auth = useAuth()
</script>

<template>
  <div v-if="auth.loggedIn">
    <p>Welcome, {{ auth.user?.name }}</p>
    <button @click="auth.logout()">Sign out</button>
  </div>
  <div v-else>
    <NuxtLink to="/login">Sign in</NuxtLink>
  </div>
</template>
auth.user is typed as UserInfo — augment that interface in a .d.ts file to get full IntelliSense on your user object’s shape (see the Installation page for an example).
4

Protect a Page

@nuxt-alt/auth registers a built-in route middleware named auth. You activate it per-page with definePageMeta — no manual middleware imports needed.Require authentication per page — apply the named auth middleware on any page where unauthenticated visitors should be redirected to auth.redirect.login:
pages/dashboard.vue
<script setup lang="ts">
definePageMeta({ middleware: 'auth' })
</script>
Guest-only page — once the middleware is active on a route, mark it as guest-only so that already-authenticated users are redirected away (useful for login and register pages):
pages/login.vue
<script setup lang="ts">
// Redirect logged-in users away from this page
definePageMeta({ middleware: 'auth', auth: 'guest' })
</script>
Opt out entirely — when globalMiddleware is true, every route runs the middleware by default. Mark individual pages as public with auth: false:
pages/about.vue
<script setup lang="ts">
// This page is publicly accessible (used when globalMiddleware: true)
definePageMeta({ auth: false })
</script>
To protect every route by default, set globalMiddleware: true in your module options. The middleware will then run on all pages, and you only need auth: false on pages you want to keep public.
The RouteMeta.auth type accepts only 'guest' or false. The value true is not valid — to require authentication on a specific page, add the middleware explicitly with middleware: 'auth'.

​
Next Steps

Local Scheme

Full reference for the local scheme — token refresh, cookie storage, custom headers, and all available endpoint options.

OAuth2 Scheme

Configure OAuth2 authorization code flows with PKCE, client-window popup authentication, and custom token endpoints.

Pre-built Providers

Drop-in provider factories for GitHub, Google, Discord, and other popular OAuth2 services — minimal configuration required.

Module Options

Complete reference for every module-level option: redirect paths, storage backends, token validation intervals, and error handling hooks.

Build docs developers (and LLMs) love

Get started for freeTalk to us