Authentication

Clerk owns identity: sign-up, sign-in, OAuth and sessions. Convex owns authorization: every query and mutation that needs a user calls ctx.auth.getUserIdentity() and checks the caller's role itself. Roles live in the Convex profiles table, not in Clerk. Nothing is protected by middleware — src/proxy.ts attaches the Clerk session but guards no route — so authorization is enforced inside Convex functions, with page-level redirects as a convenience on top.

Sign-in flows

There are two entry points, both backed by Clerk.

The modal drives Clerk's hooks directly: signIn.create({ identifier, password }) for sign-in, signUp.create(...) followed by prepareEmailAddressVerification({ strategy: "email_code" }) and attemptEmailAddressVerification({ code }) for sign-up, and signIn.authenticateWithRedirect({ strategy, redirectUrl: "/auth/sso-callback", redirectUrlComplete: "/" }) for OAuth. /auth/sso-callback renders Clerk's <AuthenticateWithRedirectCallback /> and nothing else.

The login page reads a redirect_url query parameter and sanitizes it: anything that is not a same-origin path starting with a single / falls back to /dashboard. That check is what keeps the redirect from becoming an open redirect.

From sign-in to a Convex identity

sequenceDiagram
participant U as User
participant A as AuthModal or SignIn page
participant K as Clerk
participant R as React app
participant X as Convex backend
U->>A: password, verification code or OAuth
A->>K: Clerk sign-in
K-->>R: active session
R->>K: request JWT for template convex
K-->>R: signed JWT
R->>X: query or mutation with JWT attached
X->>K: fetch JWKS from CLERK_JWT_ISSUER_DOMAIN
X->>X: ctx.auth.getUserIdentity()
R->>X: useAuth effect calls api.users.ensureProfile
X->>X: insert profiles row, role user, if none exists
X-->>R: profile

Three pieces connect Clerk to Convex:

1. src/app/layout.tsx wraps the tree in <ClerkProvider> and then <ConvexClientProvider>. When NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is missing the app renders without either provider, which is what lets CI build without Clerk secrets.
2. src/components/ConvexClientProvider.tsx uses ConvexProviderWithClerk with Clerk's useAuth, so the Convex client always sends a current token.
3. convex/auth.config.ts declares one provider: domain: process.env.CLERK_JWT_ISSUER_DOMAIN and applicationID: "convex" — matching a Clerk JWT template named convex.

Profiles are created lazily

There is no Clerk webhook and no user sync job. src/hooks/useAuth.ts calls the api.users.ensureProfile mutation once per session after Convex reports the user as authenticated; the mutation inserts a profiles row with userId: identity.subject, fullName from the Clerk identity, and role: "user" only if no row exists. The hook guards with a ref and resets it if the call fails, so it retries on the next render pass rather than looping.

A consequence worth knowing: a user can be authenticated with no profile row for a moment. api.admin.checkUserRole and api.dashboard.getDashboardData both handle a missing profile by reporting no privileges rather than throwing.

Roles and authorization

// convex/schema.ts
profiles: defineTable({
  userId: v.string(),
  fullName: v.optional(v.string()),
  role: v.union(v.literal("user"), v.literal("moderator"), v.literal("admin")),
}).index("by_userId", ["userId"]),

That field is the single source of truth. Roles are not stored in Clerk metadata and nothing syncs them. Every new profile is created as user, and there is no promotion UI or mutation — changing someone to moderator or admin means editing the profiles row in the Convex dashboard or through a one-off bunx convex run against an internal function.

flowchart TD
AN["Anonymous"] --> PUB["Public reads: jobs.listApprovedJobs, jobs.getApprovedJobFilterOptions, tags.getAllTags, emailSubscriptions.unsubscribeByToken"]
US["role: user"] --> PUB
US --> OWN["Own data: jobs.postJob, bookmarks.toggleBookmark, bookmarks.updateBookmarkStatus, bookmarks.removeTrackedApplication, profiles.updateUserName, profiles.deleteAccount, email subscription mutations"]
MO["role: moderator"] --> OWN
MO --> MOD["requireModOrAdmin: admin.getPendingJobs, admin.getApprovedJobs, admin.updateJobStatus, admin.markJobOutdated, admin.deleteJob"]
AD["role: admin"] --> MOD

admin currently grants nothing beyond moderator. The only difference is cosmetic: api.admin.checkUserRole returns isAdmin, and AdminSection titles the panel "Admin Panel" instead of "Moderator Panel". There is no user-management surface in the app.

Ownership checks are separate from role checks. bookmarks.removeTrackedApplication and bookmarks.updateBookmarkStatus load the row and throw "Unauthorized" when bookmark.userId !== identity.subject, so a valid session cannot touch another user's tracked applications.

Checking auth in a Convex function

import { mutation } from "./_generated/server";
import { requireAuth } from "./auth";

export const example = mutation({
  args: {},
  handler: async (ctx) => {
    const identity = await requireAuth(ctx); // throws "Not authenticated"
    const userId = identity.subject;         // the Clerk user id
  },
});

convex/auth.ts exports exactly two helpers: requireAuth(ctx), which throws when there is no identity, and getAuth(ctx), which returns null instead. Queries that should degrade gracefully for signed-out visitors — jobs.listApprovedJobs, bookmarks.getUserBookmarks, dashboard.getDashboardData, emailSubscriptions.getMySubscription — call ctx.auth.getUserIdentity() directly and return a safe empty result.

Route protection

What actually gates the two signed-in pages:

Neither redirect is a security boundary. /dashboard's check runs in the browser, and the moderation panel it hosts is rendered from getDashboardData, which returns an empty pendingJobs array to non-moderators and a userRole of all-false. The real boundary is requireModOrAdmin inside convex/admin.ts: a crafted client call to api.admin.updateJobStatus throws "Unauthorized" regardless of what the UI shows.

Signing out is handled by Clerk's signOut() from the header, followed by a hard navigation to / to clear client state.

The one unauthenticated mutation

api.emailSubscriptions.unsubscribeByToken takes an opaque unsubscribeToken and requires no session, because unsubscribe links have to work from an inbox. The token is a crypto.randomUUID() generated when the subscription is first created and deliberately preserved across re-subscribes, so links already sitting in old emails keep working. An unknown token returns { success: false } rather than an error. Every other subscription mutation goes through requireAuth.

Related pages

• Data Flow — how an authenticated request is served and what approval triggers
• Admin API — the moderation functions behind requireModOrAdmin
• Deployment — where each Clerk variable has to be set