Authentication

Set up authentication in your Convex + TanStack Query app.

TanStack Query is unopinionated about authentication. With Convex, auth is an implicit argument to all query functions — you don’t need to add an auth token to the query key. Queries are automatically retried when authentication state changes.

How Convex auth works with queries

Convex auth uses JWTs. Some query functions will return errors (or restricted results) if called before convexReactClient.setAuth() is invoked with a function that supplies the current token.

Because auth is implicit in the Convex client, the query key does not include auth tokens. When the user signs in or out, Convex automatically re-runs all active subscriptions with the new auth context.

Clerk setup

Wrap your app in ClerkProvider, then ConvexProviderWithClerk to wire Clerk’s auth into the Convex client. The QueryClientProvider goes inside.

import { ClerkProvider, useAuth } from "@clerk/clerk-react";
import { ConvexProviderWithClerk } from "convex/react-clerk";
import { QueryClientProvider } from "@tanstack/react-query";

<ClerkProvider publishableKey="pk_test_...">
  <ConvexProviderWithClerk client={convexClient} useAuth={useAuth}>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </ConvexProviderWithClerk>
</ClerkProvider>

Convex Auth (password) setup

If you’re using @convex-dev/auth for password-based authentication, replace ConvexProviderWithClerk with ConvexAuthProvider.

import { ConvexAuthProvider } from "@convex-dev/auth/react";
import { QueryClientProvider } from "@tanstack/react-query";

<ConvexAuthProvider client={convexClient}>
  <QueryClientProvider client={queryClient}>
    <App />
  </QueryClientProvider>
</ConvexAuthProvider>

Conditional rendering based on auth state

Use the Authenticated, Unauthenticated, and AuthLoading components from convex/react to render different UI based on auth state. These work regardless of which auth provider you use.

import { Authenticated, AuthLoading, Unauthenticated } from "convex/react";

function Main() {
  return (
    <ConvexAuthProvider client={convexClient}>
      <QueryClientProvider client={queryClient}>
        <AuthLoading><div>Loading...</div></AuthLoading>
        <Unauthenticated><SignIn /></Unauthenticated>
        <Authenticated><App /></Authenticated>
      </QueryClientProvider>
    </ConvexAuthProvider>
  );
}

See the Convex Auth docs for full setup instructions for Clerk, Auth0, and other providers.