Setting Up Clerk Auth with Convex
Step-by-step walkthrough of wiring Clerk authentication into a Convex backend with JWT validation.
By Ege Uysal
Clerk and Convex work well together, but the initial setup has a few moving parts. This guide walks through each step.
1. Configure Clerk JWT
In your Clerk dashboard, create a JWT template for Convex. Set the issuer domain and copy it. You'll need it for the Convex auth config.
2. Set Up Convex Auth
In convex/auth.config.ts, add Clerk as a provider with the JWT issuer domain. Convex will validate tokens automatically on every query and mutation.
3. Bridge the Providers
Use ConvexProviderWithClerk to pass the Clerk useAuth hook to Convex. This lets Convex attach the JWT to every request without you doing anything manually.
4. Sync User Data
Create a useSyncUser hook that watches the Clerk session and upserts user data into your Convex users table. Only write when data actually changes to avoid unnecessary mutations.
5. Protect Your Queries
In every Convex query and mutation, call ctx.auth.getUserIdentity() and compare identity.subject against the requested clerkId. This ensures users can only access their own data.