​

Clerk Authentication Setup

​

Create a Clerk Account

1. Go to Clerk Dashboard and sign up
2. Create a new application (e.g., “ZapDev”)
3. Choose your authentication methods (Email, Google, GitHub, etc.)

​

Get Your API Keys

• Publishable Key - Used in the frontend
• Secret Key - Used in the backend

​

Add Keys to Environment

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."

​

Configure JWT Template for Convex

​

Create Convex JWT Template

1. In Clerk Dashboard, go to JWT Templates
2. Click New Template → Convex
3. Name it exactly: convex
4. Click Create

​

Get JWT Issuer Domain

1. Click on the convex template
2. Copy the Issuer Domain (e.g., https://your-app.clerk.accounts.dev)
3. Add it to .env:

CLERK_JWT_ISSUER_DOMAIN="https://your-app.clerk.accounts.dev"
CLERK_JWT_TEMPLATE_NAME="convex"

​

Configure Convex to Accept Clerk Tokens

1. Go to Settings → Auth
2. Add Clerk as an auth provider
3. Enter your JWT Issuer Domain from Clerk
4. Save the configuration

​

Configure Sign-In/Sign-Up Routes

# Clerk Routes
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL="/"
NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL="/"

​

How It Works

• Sign In URL: Users are redirected to /sign-in when authentication is required
• Sign Up URL: New users are directed to /sign-up for account creation
• Fallback Redirects: After authentication, users are sent to / (home page)

​

Server-Side Authentication

​

Get Current User

import { getUser } from "@/lib/auth-server";

export default async function ProfilePage() {
  const user = await getUser();
  
  if (!user) {
    return <div>Please sign in</div>;
  }

  return <div>Welcome, {user.displayName}!</div>;
}

type AuthenticatedUser = {
  id: string;                    // Clerk user ID
  primaryEmail: string | null;   // User's email
  displayName: string | null;    // Full name, username, or first name
  imageUrl: string | null;       // Profile picture URL
};

​

Get JWT Token

import { getToken } from "@/lib/auth-server";

const token = await getToken();
// Returns JWT token with Convex template, or null if not authenticated

​

Get Authenticated Convex Client

import { getConvexClientWithAuth } from "@/lib/auth-server";

export async function createProject(name: string) {
  const convex = await getConvexClientWithAuth();
  
  return await convex.mutation(api.projects.create, {
    name,
    framework: "nextjs",
  });
}

1. Creates a Convex HTTP client
2. Retrieves the user’s JWT token
3. Sets the token for authenticated requests

​

Client-Side Authentication

​

Check Authentication Status

import { useUser } from "@clerk/nextjs";

export function UserProfile() {
  const { user, isLoaded, isSignedIn } = useUser();

  if (!isLoaded) return <div>Loading...</div>;
  if (!isSignedIn) return <div>Please sign in</div>;

  return <div>Hello, {user.fullName}!</div>;
}

​

Sign Out Button

import { useClerk } from "@clerk/nextjs";

export function SignOutButton() {
  const { signOut } = useClerk();

  return (
    <button onClick={() => signOut()}>
      Sign Out
    </button>
  );
}

​

Protecting Routes

​

Server Components

import { getUser } from "@/lib/auth-server";
import { redirect } from "next/navigation";

export default async function DashboardPage() {
  const user = await getUser();
  
  if (!user) {
    redirect("/sign-in");
  }

  return <div>Protected content</div>;
}

​

Middleware Protection

import { clerkMiddleware } from "@clerk/nextjs/server";

export default clerkMiddleware();

export const config = {
  matcher: [
    // Protect all routes except static assets
    "/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)",
  ],
};

​

Convex Integration

import { query } from "./_generated/server";

export const getUserProjects = query(async (ctx) => {
  const identity = await ctx.auth.getUserIdentity();
  
  if (!identity) {
    throw new Error("Not authenticated");
  }

  return await ctx.db
    .query("projects")
    .withIndex("by_user", (q) => q.eq("userId", identity.subject))
    .collect();
});

​

User Identity Fields

• identity.subject - Clerk user ID (use this as userId in your database)
• identity.email - User’s email address
• identity.name - User’s full name
• identity.pictureUrl - Profile picture URL

​

Testing Authentication

​

Create a Test User

1. Start your dev server: npm run dev
2. Navigate to http://localhost:3000/sign-up
3. Create an account using email or social login
4. Verify the user appears in the Clerk Dashboard → Users

​

Test Protected Routes

1. Visit a protected page while signed out (should redirect to /sign-in)
2. Sign in and verify access is granted
3. Sign out and confirm redirect behavior

​

Verify JWT Token

import { getToken } from "@/lib/auth-server";

export async function testAuth() {
  const token = await getToken();
  console.log("JWT Token:", token);
  
  // Decode the token to inspect claims (for debugging only)
  if (token) {
    const payload = JSON.parse(
      Buffer.from(token.split(".")[1], "base64").toString()
    );
    console.log("Token Payload:", payload);
  }
}

​

Production Configuration

​

Update Production Keys

1. Create a Production instance in Clerk (separate from Development)
2. Copy the production API keys
3. Update environment variables in Vercel:
   • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
   • CLERK_SECRET_KEY
   • CLERK_JWT_ISSUER_DOMAIN

​

Configure Production Domain

1. In Clerk Dashboard → Domains, add your production domain
2. Update redirect URLs to use https://your-domain.com
3. Configure CORS settings if using custom domains

​

Enable Production Features

• Email Verification: Require email verification for new signups
• 2FA: Enable two-factor authentication for enhanced security
• Session Limits: Configure session duration and token expiration
• Webhooks: Set up Clerk webhooks to sync user data with your database

​

Troubleshooting

​

”Invalid JWT” Errors

1. Verify CLERK_JWT_ISSUER_DOMAIN matches the issuer in your JWT template
2. Check that the JWT template name is exactly convex
3. Ensure Convex is configured with the correct Clerk issuer domain

​

Sign-In Redirect Loop

1. Check that NEXT_PUBLIC_CLERK_SIGN_IN_URL is set to /sign-in
2. Verify middleware is not blocking auth routes
3. Clear browser cookies and try again

​

User Identity Null in Convex

1. Confirm the user is authenticated on the client
2. Verify the Convex client is using useConvexAuth() or getConvexClientWithAuth()
3. Check that the JWT token is being sent with requests (inspect network tab)

​

Profile Picture Not Loading

1. Ensure imageUrl is not null in user object
2. Check CORS settings allow loading images from Clerk’s CDN
3. Verify the image URL is valid (test in browser)

​

Next Steps

• Configure E2B Sandboxes
• Set up Inngest
• Deploy to Vercel with production environment variables
• Configure Clerk webhooks for user sync