---
title: "Authentication"
description: "Give the Convex client a token fetcher, read the auth state anywhere, gate UI with the auth components, and keep private queries idle until sign-in."
canonical_url: "https://nuxt-convex.onmax.me/vue-guide/authentication"
---
# Authentication

> Give the Convex client a token fetcher, read the auth state anywhere, gate UI with the auth components, and keep private queries idle until sign-in.

Convex authenticates with a JWT from your auth provider (Clerk, Auth0, WorkOS, Better Auth, or any OIDC issuer that `convex/auth.config.ts` trusts). `useConvexAuth` connects that token to the realtime client and exposes the auth state.

In Nuxt with Better Auth, the module does this for you. See [Authenticated SSR](https://nuxt-convex.onmax.me/nuxt-module/authenticated-ssr) for Nuxt and custom providers.

## Configure auth once near the root

Call `useConvexAuth` with `fetchToken` once, in the root component or right after installing the plugin:

```vue [src/App.vue]
<script setup lang="ts">
import { useConvexAuth } from 'vue-convex'
import { auth } from './auth' // your provider's client SDK

useConvexAuth({
  fetchToken: async ({ forceRefreshToken }) => {
    // Return null when signed out
    return await auth.getConvexToken({ skipCache: forceRefreshToken })
  },
})
</script>
```

`auth.getConvexToken` stands for your provider's call. Convex calls `fetchToken` when the client connects and again, with `forceRefreshToken: true`, before the token expires. The fetcher is applied again whenever the runtime creates a new client, for example after `reconfigure()`.

Disposing the scope that called `useConvexAuth` signs the client out. To follow your provider's sign-in and sign-out without remounting, run it in its own effect scope:

```ts [src/convex-auth.ts]
import type { AuthTokenFetcher } from 'convex/browser'
import type { App, EffectScope } from 'vue'
import { useConvexAuth } from 'vue-convex'
import { effectScope } from 'vue'

let scope: EffectScope | undefined

export function signInConvex(app: App, fetchToken: AuthTokenFetcher) {
  scope?.stop()
  scope = effectScope(true)
  app.runWithContext(() => scope!.run(() => useConvexAuth({ fetchToken })))
}

export function signOutConvex() {
  scope?.stop() // clears the client's auth
  scope = undefined
}
```

## Read auth state anywhere below the root

```vue [src/components/NavBar.vue]
<script setup lang="ts">
import { useConvexAuth } from 'vue-convex'

const { isLoading, isAuthenticated } = useConvexAuth()
</script>
```

`isAuthenticated` turns `true` once Convex has validated the token, not when your provider signs in. That's the moment queries start running as the user.

## Gate UI with the auth components

```vue [src/App.vue]
<script setup lang="ts">
import { ConvexAuthenticated, ConvexAuthLoading, ConvexUnauthenticated } from 'vue-convex'
</script>

<template>
  <ConvexAuthLoading>
    <p>Checking authentication…</p>
  </ConvexAuthLoading>

  <ConvexAuthenticated>
    <Dashboard />
  </ConvexAuthenticated>

  <ConvexUnauthenticated>
    <LoginPage />
  </ConvexUnauthenticated>
</template>
```

They render nothing before the component mounts unless the plugin received `initialAuth`, which is what server rendering uses to avoid a flash. In Nuxt they're auto-imported, and the server knows the state.

## Keep private queries idle until sign-in

```ts
const { data } = useConvexQuery(api.tasks.mine, {}, { auth: 'required' })
```

The query stays `idle` until `isAuthenticated` is `true`, then subscribes as the user. When the user signs out it goes back to `idle` and `data` is cleared.

## Verify the result

The auth setup is working when:

- `isLoading` becomes `false`
- `isAuthenticated` reflects the current session
- private queries stay `idle` until the user is signed in
- in Convex functions, `ctx.auth.getUserIdentity()` returns the user

## Next steps

- Read [Controller](https://nuxt-convex.onmax.me/vue-guide/controller) if the runtime connects only after sign-in
- Read [`useConvexAuth`](https://nuxt-convex.onmax.me/api-reference/use-convex-auth) for the exact API surface


## Sitemap

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