Clerk Authentication

How CodeCourier uses Clerk for user authentication, session management, and identity, including OAuth providers, SSO, and customization.

7 min read
clerkauthenticationoauth

Clerk is the authentication and user management platform that handles all identity operations in CodeCourier. From sign-up to session management to webhook-driven account cleanup, Clerk provides a complete authentication solution that integrates seamlessly with the Next.js frontend and Convex backend. This page covers how CodeCourier uses Clerk, setup instructions, and customization options.

What Clerk Provides

Clerk is a developer-focused authentication platform that offers:

  • Multiple sign-in methods -- Email and password, OAuth providers (Google, GitHub, and others), magic links, and more.
  • Pre-built UI components -- Drop-in sign-in and sign-up forms that handle the complete authentication flow.
  • JWT issuance -- Signed JWTs that integrate with backend services like Convex for server-side identity verification.
  • User management -- User profiles, metadata, and account settings through a hosted dashboard.
  • Webhook events -- Notifications for user lifecycle events such as account creation and deletion.
  • Session management -- Automatic session refresh, multi-device support, and secure cookie handling.

How CodeCourier Uses Clerk

Authentication Flow

CodeCourier uses the @clerk/nextjs SDK (version 6+) to integrate Clerk with the Next.js app router. The integration includes:

  • Sign-in and sign-up pages -- Located at /sign-in and /sign-up, these use Clerk's pre-built components styled to match CodeCourier's design system.
  • Route protection -- The Next.js proxy (proxy.ts) intercepts requests and redirects unauthenticated users to the sign-in page for protected routes.
  • Convex integration -- The ConvexProviderWithClerk component wraps the app and automatically passes Clerk session tokens to the Convex client for server-side authentication.

User Record Synchronization

When a user signs in for the first time, CodeCourier creates a corresponding record in the Convex users table. This record stores:

  • clerkId -- The Clerk user ID, used for lookups via the by_clerk_id index.
  • email-- The user's primary email address.
  • name-- The user's display name (optional).
  • imageUrl-- The user's avatar URL from their Clerk profile or OAuth provider.
  • role -- An optional application-level role (not to be confused with project membership roles).

Session Management

Clerk handles session lifecycle automatically. Sessions are maintained through secure HTTP-only cookies with automatic refresh. The @clerk/nextjs SDK provides middleware (implemented as proxy.ts in Next.js 16) that validates the session on every request and makes the user identity available to server components and API routes.

Account Deletion

When a user deletes their Clerk account, the /clerk/webhook endpoint receives a user.deletedevent. This triggers cleanup of the user's data in Convex. The webhook uses Svix signature verification for security (see the Webhooks page for verification details).

Setup and Configuration

Environment Variables

Three environment variables are required for Clerk integration:

  • NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY -- The public key from your Clerk dashboard. Used by the frontend SDK for client-side operations.
  • CLERK_SECRET_KEY -- The secret key from your Clerk dashboard. Used by the server-side SDK for session validation and API calls.
  • CLERK_WEBHOOK_SECRET -- The Svix signing secret for webhook verification. Obtained from the webhooks section of your Clerk dashboard.

Clerk Dashboard Configuration

  1. Create a Clerk application at clerk.com.
  2. Configure the sign-in methods you want to support (email/ password, Google OAuth, GitHub OAuth, etc.).
  3. Copy the publishable key and secret key to your environment variables.
  4. Set up a webhook endpoint pointing to your Convex deployment URL followed by /clerk/webhook.
  5. Subscribe to the user.deleted event (and any other events you want to handle).
  6. Copy the webhook signing secret to your CLERK_WEBHOOK_SECRET environment variable.

User Management

User Profiles

User profile information is managed primarily through Clerk. The Clerk-hosted user profile page allows users to:

  • Update their display name and avatar
  • Change their email address
  • Manage connected OAuth accounts
  • Update their password
  • Enable or disable two-factor authentication

CodeCourier reads profile information from Clerk through the session JWT and displays it in the dashboard header, user avatar component, and project member lists.

User Preferences

Application-specific preferences (such as the last active project) are stored in the Convex userSettings table, separate from the Clerk profile. This separation keeps Clerk focused on identity while Convex manages application state.

OAuth and Social Authentication

Clerk supports numerous OAuth providers out of the box. To add a social sign-in option:

  1. Navigate to User & Authentication > Social Connections in the Clerk dashboard.
  2. Enable the desired provider (Google, GitHub, etc.).
  3. Configure the OAuth app credentials (client ID and secret) for production deployments.

No code changes are needed in CodeCourier -- the Clerk sign-in components automatically show buttons for all enabled providers.

Customization

Theme Integration

CodeCourier customizes the Clerk sign-in and sign-up components using the @clerk/themes package. The appearance configuration is defined in lib/clerk-appearance.ts and ensures that Clerk components match CodeCourier's design system, including dark mode support and consistent typography.

Auth Guard

The AuthGuard component provides client-side route protection. It checks the Clerk session status and redirects unauthenticated users to the sign-in page. This works alongside the server-side proxy for defense in depth.

GDPR and Data Privacy

CodeCourier implements a consent management system alongside Clerk authentication. The consents and consentHistory tables track user consent for essential, analytics, marketing, and functional data processing. Users can submit data requests (export, deletion, restriction, objection, rectification) through the dataRequests system.

When a user requests account deletion through CodeCourier, the system processes the request internally and can trigger the Clerk account deletion if needed. Conversely, if a user deletes their Clerk account directly, the webhook ensures CodeCourier is notified and can clean up accordingly.