---
title: "Auth State"
description: "The always-on, provider-agnostic Convex auth plumbing — provideConvexAuth, useConvexAuth, and the four state components."
canonical_url: "https://nuxt-convex-module.dev/guide/auth-state"
---
# Auth State

> The always-on, provider-agnostic Convex auth plumbing — provideConvexAuth, useConvexAuth, and the four state components.

The core ships the generic Convex auth plumbing — a port of `convex/react`'s `ConvexProviderWithAuth`. It is **provider-agnostic**: it knows nothing about Clerk, Auth0, or Better Auth, and it is always available whether or not you have installed one of them.

<callout icon="i-lucide-blocks">

Looking for a specific provider? The adapters live in [Components](https://nuxt-convex-module.dev/components) — [Better Auth](https://nuxt-convex-module.dev/components/better-auth), [Clerk](https://nuxt-convex-module.dev/components/clerk), and [Auth0](https://nuxt-convex-module.dev/components/auth0). Each one wires itself into the plumbing on this page.

</callout>

## `provideConvexAuth()`

`provideConvexAuth({ client, useAuth })` wires any auth provider's loading/authenticated flags and token fetcher into the Convex client.

Re-authentication has two triggers: pass `fetchAccessToken` as a `Ref` whose identity changes, or return the additive `authVersion` key (`MaybeRefOrGetter<unknown>`) — when either changes, auth state transitions back to loading and the token is fetched again. The bundled adapters rely on this (Clerk keys `authVersion` off the active org id, org role and session id; Better Auth off the session id).

Your `useAuth` composable returns `{ isLoading, isAuthenticated, fetchAccessToken }` plus the optional `authVersion`. `fetchAccessToken` is an async function returning the JWT (or `null`).

Under Nuxt the adapters call this for you; in a plain Vue app you call it yourself — see [Plain Vue](https://nuxt-convex-module.dev/guide/plain-vue#auth-wiring), which also covers `createScopedConvexAuthState` for installing auth state outside a component setup.

## `useConvexAuth()`

Read `{ isLoading, isAuthenticated, isRefreshing }` anywhere below the provider. Each field is a `ComputedRef<boolean>`, so the upstream destructuring idiom stays reactive:

```ts
const { isLoading, isAuthenticated } = useConvexAuth()
// isAuthenticated.value in script, plain `isAuthenticated` in templates
```

`isRefreshing` is `true` only while an already-authenticated session is re-fetching a token the server rejected — the socket is paused meanwhile. Routine background token rotation does not trigger it.

`useConvexAuth()` throws `Could not find Convex auth context` when nothing has provided auth state: a Nuxt app with no auth integration (the base client plugin provides none), an adapter called below the consumer, or a plain Vue app without `provideConvexAuth()`. The state components throw the same way.

## State components

Four auto-imported components render their default slot by auth state:

```vue
<template>
  <Authenticated>Welcome back</Authenticated>
  <Unauthenticated>Please sign in</Unauthenticated>
  <AuthLoading>Checking…</AuthLoading>
  <AuthRefreshing>Refreshing your session…</AuthRefreshing>
</template>
```

What the server renders depends on what the provider reports during SSR. Under Better Auth that is always *loading* — see [server rendering](https://nuxt-convex-module.dev/components/better-auth#server-rendering).

None of them takes props — each is a default slot rendered under one condition:

<table>
<thead>
  <tr>
    <th>
      Component
    </th>
    
    <th>
      Renders its slot when
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        <Authenticated>
      </code>
    </td>
    
    <td>
      <code>
        !isLoading && isAuthenticated
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <Unauthenticated>
      </code>
    </td>
    
    <td>
      <code>
        !isLoading && !isAuthenticated
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <AuthLoading>
      </code>
    </td>
    
    <td>
      <code>
        isLoading
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <AuthRefreshing>
      </code>
    </td>
    
    <td>
      <code>
        isAuthenticated && isRefreshing
      </code>
      
       — an authenticated session re-fetching a rejected token
    </td>
  </tr>
</tbody>
</table>

They read the same state `useConvexAuth()` exposes, so they work under any provider — or under a hand-rolled one.


## Sitemap

See the full [sitemap](https://nuxt-convex-module.dev/sitemap.md) for all pages.