Vue Guide

Authentication

Configure auth state for the shared Convex runtime and gate queries or UI on the current session.

Use useConvexAuth to connect a token fetcher to the Convex client and expose shared auth state in your component tree.

Configure auth once near the root

Call useConvexAuth with fetchToken in a root component.

src/App.vue

<script setup lang="ts">
import { useConvexAuth } from 'vue-convex'

const { isLoading, isAuthenticated } = useConvexAuth({
  fetchToken: async ({ forceRefreshToken }) => {
    return await myAuthProvider.getToken({ forceRefreshToken })
  },
})
</script>

The shared runtime re-applies that token fetcher when the client reconnects.

Read auth state anywhere below the root

Child components call useConvexAuth() without options to read the current state.

src/components/Nav.vue

<script setup lang="ts">
import { useConvexAuth } from 'vue-convex'

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

Gate UI with the renderless components

src/App.vue

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

  <ConvexAuthenticated>
    <Dashboard />
  </ConvexAuthenticated>

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

These components are client-only. They do not render their slots on the server.

Skip private queries until the user is signed in

src/components/Dashboard.vue

<script setup lang="ts">
import { useConvexAuth, useConvexQuery } from 'vue-convex'
import { api } from '../convex/_generated/api'

const { isAuthenticated } = useConvexAuth()

const { data } = useConvexQuery(
  api.tasks.myTasks,
  computed(() => isAuthenticated.value ? {} : 'skip'),
)
</script>

Verify the result

The auth setup is working when:

isLoading becomes false
isAuthenticated reflects the current session
private queries stay skipped until the user is signed in

Next steps

Read Controller if the runtime connects only after sign-in
Read useConvexAuth for the exact API surface

Edit this pageorReport an issue

Controller

Connect, reconfigure, or disconnect the Convex runtime explicitly when the deployment URL is not available at startup.

Connection State

Monitor the Convex realtime connection and react to disconnects in your UI.