Skip to main content

Route protection

Redirect anonymous navigation while preserving backend authorization as the security boundary.

Route protection waits until the auth state is known, then redirects anonymous users. It controls navigation only. It does not protect Convex data.

Configure defaults

nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@lupinum/better-convex-nuxt'],
  convex: {
    auth: {
      origin: process.env.SITE_URL,
      redirectTo: '/auth/sign-in',
    },
  },
})

Protect a page

ts
definePageMeta({
  convexAuth: true,
})

For a page-specific destination:

ts
definePageMeta({
  convexAuth: { redirectTo: '/account/login' },
})

Only local redirect paths are accepted. Protocol-relative paths, backslashes, control characters, and unsafe decoded paths are rejected. An unsafe page-specific redirectTo falls back to convex.auth.redirectTo; the page stays protected.

When auth is temporarily unavailable

The server and the browser use one rule for a failed attempt to learn who is signed in:

Answer from the auth backendMeaningWhat happens
No answer, a timeout, 408, 429, or 5xxTemporaryThe session stays, error.code is AUTH_UNAVAILABLE, and the browser retries
401 or 403The session is rejectedThe session ends, and the middleware redirects
Any other status, for example a redirect or a 404, or a token without a usable lifetime or subSetup errorerror.code is AUTH_MISCONFIGURED, and the middleware redirects

A temporary failure says nothing about the person. The middleware does not redirect then: it renders the protected page with useConvexAuth().status set to 'error' (or still 'pending' while the browser waits out the failure). The browser reads the session again with backoff (2 s, 4 s, up to 60 s) and recovers on its own. Check error.code, not error.message; the message is display text and can change. Show that state instead of a signed-out view:

vue
<script setup lang="ts">
const { error } = useConvexAuth()
</script>

<template>
  <p v-if="error?.code === 'AUTH_UNAVAILABLE'">Reconnecting…</p>
  <slot v-else />
</template>

Convex still refuses data the person may not read, and queries with auth: 'required' stay idle until the identity is known. Any other failure still redirects.

A session-changing call on client, for example client.updateUser(), that meets a temporary failure rejects with AUTH_UNAVAILABLE. The session stays.

Keep signed-in users off guest pages

Mark a sign-in or sign-up page as guest-only:

app/pages/auth/sign-in.vue
definePageMeta({
  convexAuth: 'guest',
})

A signed-out visitor sees the page. A signed-in visitor goes to the validated redirect query path, or else to convex.auth.guestRedirectTo (default /). The middleware never redirects to the current page, and it ignores a repeated redirect parameter.

Preserve the return path

The middleware always appends a validated local redirect query value. After sign-in, read it with useConvexAuthReturnTo(). It returns the normalized path, or null when the value is missing, repeated, or unsafe:

app/pages/auth/sign-in.vue
const returnTo = useConvexAuthReturnTo()

async function afterSignIn() {
  await navigateTo(returnTo.value ?? '/dashboard')
}

To validate another value, call normalizeLocalRedirectPath(value). It accepts any input and returns a safe local path or null. Never navigate to an external URL from a query parameter.

Public pages

Pages without convexAuth metadata remain public by default. An authenticated application can combine public auth: 'none' content and private controls on the same page without protecting the route.

To protect every page by default, set routes: 'protected':

nuxt.config.ts
export default defineNuxtConfig({
  convex: {
    auth: {
      origin: process.env.SITE_URL,
      redirectTo: '/auth/sign-in',
      routes: 'protected',
    },
  },
})

Then a page without metadata requires sign-in. Opt a public page out with definePageMeta({ convexAuth: false }). The sign-in page never redirects to itself.

Permission checks

Authentication can be resolved in middleware. Product permissions normally require backend data.

Prefer to render the page and query the user's permissions from Convex, unless the navigation itself must be blocked. A permission check in middleware only changes what the user sees. The Convex function must repeat the check.

Caching warning

Do not cache an authenticated SSR page as public HTML. A redirect middleware does not split a shared cache by user.