| name | convex-clerk |
| description | Clerk authentication integration for Convex. Use when setting up Clerk auth, configuring ConvexProviderWithClerk, implementing Clerk webhooks for user sync, or troubleshooting Clerk-specific auth issues. |
Convex + Clerk Authentication
Provider-specific patterns for integrating Clerk with Convex.
Required Configuration
1. auth.config.ts
import { AuthConfig } from 'convex/server';
export default {
providers: [
{
domain: process.env.CLERK_JWT_ISSUER_DOMAIN!,
applicationID: 'convex'
}
]
} satisfies AuthConfig;
CRITICAL: JWT template in Clerk MUST be named exactly convex.
2. Environment Variables
VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
CLERK_JWT_ISSUER_DOMAIN=https://verb-noun-00.clerk.accounts.dev
CLERK_WEBHOOK_SECRET=whsec_...
Client Setup
React (Vite)
import { ClerkProvider, useAuth } from "@clerk/clerk-react";
import { ConvexProviderWithClerk } from "convex/react-clerk";
import { ConvexReactClient } from "convex/react";
const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);
ReactDOM.createRoot(document.getElementById("root")!).render(
<ClerkProvider publishableKey={import.meta.env.VITE_CLERK_PUBLISHABLE_KEY}>
<ConvexProviderWithClerk client={convex} useAuth={useAuth}>
<App />
</ConvexProviderWithClerk>
</ClerkProvider>
);
Next.js App Router
'use client';
import { ReactNode } from 'react';
import { ConvexReactClient } from 'convex/react';
import { ConvexProviderWithClerk } from 'convex/react-clerk';
import { useAuth } from '@clerk/nextjs';
const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
export default function ConvexClientProvider({ children }: { children: ReactNode }) {
return (
<ConvexProviderWithClerk client={convex} useAuth={useAuth}>
{children}
</ConvexProviderWithClerk>
);
}
import { ClerkProvider } from '@clerk/nextjs';
import ConvexClientProvider from '@/components/ConvexClientProvider';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html>
<body>
<ClerkProvider>
<ConvexClientProvider>{children}</ConvexClientProvider>
</ClerkProvider>
</body>
</html>
);
}
Next.js Middleware
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server';
const isProtectedRoute = createRouteMatcher(['/dashboard(.*)']);
export default clerkMiddleware(async (auth, req) => {
if (isProtectedRoute(req)) {
await auth.protect();
}
});
export const config = {
matcher: ['/((?!.*\\..*|_next).*)', '/', '/(api|trpc)(.*)']
};
UI Components
Use Convex auth components, NOT Clerk's:
import { Authenticated, Unauthenticated, AuthLoading } from 'convex/react';
import { SignedIn, SignedOut } from '@clerk/clerk-react';
import { SignInButton, UserButton } from "@clerk/clerk-react";
import { Authenticated, Unauthenticated } from "convex/react";
function App() {
return (
<>
<Authenticated>
<UserButton />
<Content />
</Authenticated>
<Unauthenticated>
<SignInButton />
</Unauthenticated>
</>
);
}
Clerk Webhooks for User Sync
See WEBHOOKS.md for complete implementation.
Setup in Clerk Dashboard:
- Webhooks > Add Endpoint
- URL:
https://your-deployment.convex.site/clerk-users-webhook
- Events: Select all
user.* events
- Copy Signing Secret → Convex Dashboard env vars as
CLERK_WEBHOOK_SECRET
Accessing User Info
Client-side (Clerk SDK)
import { useUser } from "@clerk/clerk-react";
function Profile() {
const { user } = useUser();
return <span>Hello, {user?.fullName}</span>;
}
Server-side (Convex functions)
export const myQuery = query({
handler: async (ctx) => {
const identity = await ctx.auth.getUserIdentity();
}
});
Dev vs Prod Configuration
| Environment | Publishable Key | Issuer Domain |
|---|
| Development | pk_test_... | https://verb-noun-00.clerk.accounts.dev |
| Production | pk_live_... | https://clerk.your-domain.com |
Set different values in Convex Dashboard for dev vs prod deployments.
Clerk-Specific Troubleshooting
| Issue | Cause | Fix |
|---|
| Token not generated | JWT template not named "convex" | Rename template to exactly convex |
aud mismatch | Wrong applicationID | Use applicationID: "convex" |
iss mismatch | Wrong domain | Copy Frontend API URL from Clerk |
| Webhook fails | Wrong secret | Copy Signing Secret from Clerk webhook |
DO ✅
- Name JWT template exactly
convex
- Use
ConvexProviderWithClerk with useAuth from Clerk
- Use
useConvexAuth() not Clerk's useAuth() for auth state
- Use Convex's
<Authenticated> not Clerk's <SignedIn>
- Set CLERK_JWT_ISSUER_DOMAIN in Convex Dashboard
DON'T ❌
- Rename the JWT template from "convex"
- Use Clerk's auth hooks to gate Convex queries
- Hardcode the issuer domain (use env var)
- Forget to deploy after changing auth.config.ts
