Convex Setup Auth

1---2name: convex-setup-auth3description: Sets up Convex authentication with user management, identity mapping, and access control. Use this skill when adding login or signup to a Convex app, configuring Convex Auth, Clerk, WorkOS AuthKit, Auth0, or custom JWT providers, wiring auth.config.ts, protecting queries and mutations with ctx.auth.getUserIdentity(), creating a users table with identity mapping, or setting up role-based access control, even if the user just says "add auth" or "make it require login."4---5 6# Convex Authentication Setup7 8Implement secure authentication in Convex with user management and access control.9 10## When to Use11 12- Setting up authentication for the first time13- Implementing user management (users table, identity mapping)14- Creating authentication helper functions15- Setting up auth providers (Convex Auth, Clerk, WorkOS AuthKit, Auth0, custom JWT)16 17## When Not to Use18 19- Auth for a non-Convex backend20- Pure OAuth/OIDC documentation without a Convex implementation21- Debugging unrelated bugs that happen to surface near auth code22- The auth provider is already fully configured and the user only needs a one-line fix23 24## First Step: Choose the Auth Provider25 26Convex supports multiple authentication approaches. Do not assume a provider.27 28Before writing setup code:29 301. Ask the user which auth solution they want, unless the repository already makes it obvious312. If the repo already uses a provider, continue with that provider unless the user wants to switch323. If the user has not chosen a provider and the repo does not make it obvious, ask before proceeding33 34Common options:35 36- [Convex Auth](https://docs.convex.dev/auth/convex-auth) - good default when the user wants auth handled directly in Convex37- [Clerk](https://docs.convex.dev/auth/clerk) - use when the app already uses Clerk or the user wants Clerk's hosted auth features38- [WorkOS AuthKit](https://docs.convex.dev/auth/authkit/) - use when the app already uses WorkOS or the user wants AuthKit specifically39- [Auth0](https://docs.convex.dev/auth/auth0) - use when the app already uses Auth040- Custom JWT provider - use when integrating an existing auth system not covered above41 42Look for signals in the repo before asking:43 44- Dependencies such as `@clerk/*`, `@workos-inc/*`, `@auth0/*`, or Convex Auth packages45- Existing files such as `convex/auth.config.ts`, auth middleware, provider wrappers, or login components46- Environment variables that clearly point at a provider47 48## After Choosing a Provider49 50Read the provider's official guide and the matching local reference file:51 52- Convex Auth: [official docs](https://docs.convex.dev/auth/convex-auth), then `references/convex-auth.md`53- Clerk: [official docs](https://docs.convex.dev/auth/clerk), then `references/clerk.md`54- WorkOS AuthKit: [official docs](https://docs.convex.dev/auth/authkit/), then `references/workos-authkit.md`55- Auth0: [official docs](https://docs.convex.dev/auth/auth0), then `references/auth0.md`56 57The local reference files contain the concrete workflow, expected files and env vars, gotchas, and validation checks.58 59Use those sources for:60 61- package installation62- client provider wiring63- environment variables64- `convex/auth.config.ts` setup65- login and logout UI patterns66- framework-specific setup for React, Vite, or Next.js67 68For shared auth behavior, use the official Convex docs as the source of truth:69 70- [Auth in Functions](https://docs.convex.dev/auth/functions-auth) for `ctx.auth.getUserIdentity()`71- [Storing Users in the Convex Database](https://docs.convex.dev/auth/database-auth) for optional app-level user storage72- [Authentication](https://docs.convex.dev/auth) for general auth and authorization guidance73- [Convex Auth Authorization](https://labs.convex.dev/auth/authz) when the provider is Convex Auth74 75Prefer official docs over recalled steps, because provider CLIs and Convex Auth internals change between versions. Inventing setup from memory risks outdated patterns.76For third-party providers, only add app-level user storage if the app actually needs user documents in Convex. Not every app needs a `users` table.77For Convex Auth, follow the Convex Auth docs and built-in auth tables rather than adding a parallel `users` table plus `storeUser` flow, because Convex Auth already manages user records internally.78After running provider initialization commands, verify generated files and complete the post-init wiring steps the provider reference calls out. Initialization commands rarely finish the entire integration.79 80## Core Pattern: Protecting Backend Functions81 82The most common auth task is checking identity in Convex functions.83 84```ts85// Bad: trusting a client-provided userId86export const getMyProfile = query({87  args: { userId: v.id("users") },88  handler: async (ctx, args) => {89    return await ctx.db.get(args.userId);90  },91});92```93 94```ts95// Good: verifying identity server-side96export const getMyProfile = query({97  args: {},98  handler: async (ctx) => {99    const identity = await ctx.auth.getUserIdentity();100    if (!identity) throw new Error("Not authenticated");101 102    return await ctx.db103      .query("users")104      .withIndex("by_tokenIdentifier", (q) =>105        q.eq("tokenIdentifier", identity.tokenIdentifier),106      )107      .unique();108  },109});110```111 112## Workflow113 1141. Determine the provider, either by asking the user or inferring from the repo1152. Ask whether the user wants local-only setup or production-ready setup now1163. Read the matching provider reference file1174. Follow the official provider docs for current setup details1185. Follow the official Convex docs for shared backend auth behavior, user storage, and authorization patterns1196. Only add app-level user storage if the docs and app requirements call for it1207. Add authorization checks for ownership, roles, or team access only where the app needs them1218. Verify login state, protected queries, environment variables, and production configuration if requested122 123If the flow blocks on interactive provider or deployment setup, ask the user explicitly for the exact human step needed, then continue after they complete it.124For UI-facing auth flows, offer to validate the real sign-up or sign-in flow after setup is done.125If the environment has browser automation tools, you can use them.126If it does not, give the user a short manual validation checklist instead.127 128## Reference Files129 130### Provider References131 132- `references/convex-auth.md`133- `references/clerk.md`134- `references/workos-authkit.md`135- `references/auth0.md`136 137## Checklist138 139- [ ] Chosen the correct auth provider before writing setup code140- [ ] Read the relevant provider reference file141- [ ] Asked whether the user wants local-only setup or production-ready setup142- [ ] Used the official provider docs for provider-specific wiring143- [ ] Used the official Convex docs for shared auth behavior and authorization patterns144- [ ] Only added app-level user storage if the app actually needs it145- [ ] Did not invent a cross-provider `users` table or `storeUser` flow for Convex Auth146- [ ] Added authentication checks in protected backend functions147- [ ] Added authorization checks where the app actually needs them148- [ ] Clear error messages ("Not authenticated", "Unauthorized")149- [ ] Client auth provider configured for the chosen provider150- [ ] If requested, production auth setup is covered too