---
title: "useConvexAuth"
description: "Reference for the auth-state composable and the ConvexAuthenticated, ConvexUnauthenticated and ConvexAuthLoading components."
canonical_url: "https://nuxt-convex.onmax.me/api-reference/use-convex-auth"
---
# useConvexAuth

> Reference for the auth-state composable and the ConvexAuthenticated, ConvexUnauthenticated and ConvexAuthLoading components.

`useConvexAuth` reads the Convex auth state. Called once with `fetchToken`, it also authenticates the realtime client.

## Import

```ts [Nuxt]
// Auto-imported. Also exported from '#convex'.
const { isLoading, isAuthenticated } = useConvexAuth()
```

```ts [Vue]
import { useConvexAuth } from 'vue-convex'
```

## Signature

```ts
function useConvexAuth(options?: {
  fetchToken?: AuthTokenFetcher
}): {
  isLoading: ComputedRef<boolean>
  isAuthenticated: ComputedRef<boolean>
}
```

`AuthTokenFetcher` is the `convex/browser` type: `(args: { forceRefreshToken: boolean }) => Promise<string | null | undefined>`.

## Behavior

- Call it with `fetchToken` once, in a plugin or the root component, to authenticate the realtime client. Call it without options anywhere else to read the state.
- The token fetcher is applied again whenever the runtime creates a new client, for example after `reconfigure()`.
- Disposing the scope that passed `fetchToken` signs the client out and resets the state.
- `fetchToken` is ignored on the server. Server-side auth goes through `serverAuth` in Vue, and the [token provider](https://nuxt-convex.onmax.me/nuxt-module/authenticated-ssr) in Nuxt.
- In Nuxt with the Better Auth provider, the module calls it for you. Don't call it with `fetchToken` yourself.
- When SSR rendered a signed-in user, the client keeps that state until Convex confirms the token, so the page doesn't flip to loading during hydration.

## Auth components

`ConvexAuthenticated`, `ConvexUnauthenticated` and `ConvexAuthLoading` render their default slot when the user is signed in, signed out, or still loading.

```vue [app/components/AccountMenu.vue]
<template>
  <ConvexAuthLoading>
    <span>Checking session…</span>
  </ConvexAuthLoading>
  <ConvexAuthenticated>
    <UserMenu />
  </ConvexAuthenticated>
  <ConvexUnauthenticated>
    <NuxtLink to="/login">Sign in</NuxtLink>
  </ConvexUnauthenticated>
</template>
```

- In Nuxt they're auto-imported. In Vue, import them from `vue-convex`.
- Until the component mounts, they render the state the server rendered with, so hydration matches. After mounting they follow the live state.
- In Nuxt the server resolves the state for every request (signed out when neither a provider nor the `convex:token` hook supplies a token), so the matching slot is in the SSR HTML. If your app only signs in on the client, render signed-in UI after mount to avoid a flash of the signed-out slot.
- In plain Vue, they render nothing until mounted unless you pass `initialAuth` to the plugin.

## Related pages

- [Authentication](https://nuxt-convex.onmax.me/vue-guide/authentication)
- [Authenticated SSR](https://nuxt-convex.onmax.me/nuxt-module/authenticated-ssr)
- [useConvexQuery](https://nuxt-convex.onmax.me/api-reference/use-convex-query)


## Sitemap

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