1---
2name: convex-setup-auth
3description:
4  Sets up Convex auth, identity mapping, and access control. Use for login, auth
5  providers, users tables, protected functions, or roles in a Convex app.
6---
7 
8# Convex Authentication Setup
9 
10Implement secure authentication in Convex with user management and access
11control.
12 
13## When to Use
14 
15- Setting up authentication for the first time
16- Implementing user management (users table, identity mapping)
17- Creating authentication helper functions
18- Setting up auth providers (Convex Auth, Clerk, WorkOS AuthKit, Auth0, custom
19  JWT)
20 
21## When Not to Use
22 
23- Auth for a non-Convex backend
24- Pure OAuth/OIDC documentation without a Convex implementation
25- Debugging unrelated bugs that happen to surface near auth code
26- The auth provider is already fully configured and the user only needs a
27  one-line fix
28 
29## First Step: Choose the Auth Provider
30 
31Convex supports multiple authentication approaches. Do not assume a provider.
32 
33Before writing setup code:
34 
351. Ask the user which auth solution they want, unless the repository already
36   makes it obvious
372. If the repo already uses a provider, continue with that provider unless the
38   user wants to switch
393. If the user has not chosen a provider and the repo does not make it obvious,
40   ask before proceeding
41 
42Common options:
43 
44- [Convex Auth](https://docs.convex.dev/auth/convex-auth) - good default when
45  the user wants auth handled directly in Convex
46- [Clerk](https://docs.convex.dev/auth/clerk) - use when the app already uses
47  Clerk or the user wants Clerk's hosted auth features
48- [WorkOS AuthKit](https://docs.convex.dev/auth/authkit/) - use when the app
49  already uses WorkOS or the user wants AuthKit specifically
50- [Auth0](https://docs.convex.dev/auth/auth0) - use when the app already uses
51  Auth0
52- Custom JWT provider - use when integrating an existing auth system not covered
53  above
54 
55Look for signals in the repo before asking:
56 
57- Dependencies such as `@clerk/*`, `@workos-inc/*`, `@auth0/*`, or Convex Auth
58  packages
59- Existing files such as `convex/auth.config.ts`, auth middleware, provider
60  wrappers, or login components
61- Environment variables that clearly point at a provider
62 
63## After Choosing a Provider
64 
65Read the provider's official guide and the matching local reference file:
66 
67- Convex Auth: [official docs](https://docs.convex.dev/auth/convex-auth), then
68  `references/convex-auth.md`
69- Clerk: [official docs](https://docs.convex.dev/auth/clerk), then
70  `references/clerk.md`
71- WorkOS AuthKit: [official docs](https://docs.convex.dev/auth/authkit/), then
72  `references/workos-authkit.md`
73- Auth0: [official docs](https://docs.convex.dev/auth/auth0), then
74  `references/auth0.md`
75 
76The local reference files contain the concrete workflow, expected files and env
77vars, gotchas, and validation checks.
78 
79Use those sources for:
80 
81- package installation
82- client provider wiring
83- environment variables
84- `convex/auth.config.ts` setup
85- login and logout UI patterns
86- framework-specific setup for React, Vite, or Next.js
87 
88For shared auth behavior, use the official Convex docs as the source of truth:
89 
90- [Auth in Functions](https://docs.convex.dev/auth/functions-auth) for
91  `ctx.auth.getUserIdentity()`
92- [Storing Users in the Convex Database](https://docs.convex.dev/auth/database-auth)
93  for optional app-level user storage
94- [Authentication](https://docs.convex.dev/auth) for general auth and
95  authorization guidance
96- [Convex Auth Authorization](https://labs.convex.dev/auth/authz) when the
97  provider is Convex Auth
98 
99Prefer official docs over recalled steps, because provider CLIs and Convex Auth
100internals change between versions. Inventing setup from memory risks outdated
101patterns. For third-party providers, only add app-level user storage if the app
102actually needs user documents in Convex. Not every app needs a `users` table.
103For Convex Auth, follow the Convex Auth docs and built-in auth tables rather
104than adding a parallel `users` table plus `storeUser` flow, because Convex Auth
105already manages user records internally. After running provider initialization
106commands, verify generated files and complete the post-init wiring steps the
107provider reference calls out. Initialization commands rarely finish the entire
108integration.
109 
110## Core Pattern: Protecting Backend Functions
111 
112The most common auth task is checking identity in Convex functions.
113 
114```ts
115// Bad: trusting a client-provided userId
116export const getMyProfile = query({
117  args: { userId: v.id("users") },
118  handler: async (ctx, args) => {
119    return await ctx.db.get(args.userId);
120  },
121});
122```
123 
124```ts
125// Good: verifying identity server-side
126export const getMyProfile = query({
127  args: {},
128  handler: async (ctx) => {
129    const identity = await ctx.auth.getUserIdentity();
130    if (!identity) throw new Error("Not authenticated");
131 
132    return await ctx.db
133      .query("users")
134      .withIndex("by_tokenIdentifier", (q) =>
135        q.eq("tokenIdentifier", identity.tokenIdentifier),
136      )
137      .unique();
138  },
139});
140```
141 
142## Workflow
143 
1441. Determine the provider, either by asking the user or inferring from the repo
1452. Ask whether the user wants local-only setup or production-ready setup now
1463. Read the matching provider reference file
1474. Follow the official provider docs for current setup details
1485. Follow the official Convex docs for shared backend auth behavior, user
149   storage, and authorization patterns
1506. Only add app-level user storage if the docs and app requirements call for it
1517. Add authorization checks for ownership, roles, or team access only where the
152   app needs them
1538. Verify login state, protected queries, environment variables, and production
154   configuration if requested
155 
156If the flow blocks on interactive provider or deployment setup, ask the user
157explicitly for the exact human step needed, then continue after they complete
158it. For UI-facing auth flows, offer to validate the real sign-up or sign-in flow
159after setup is done. If the environment has browser automation tools, you can
160use them. If it does not, give the user a short manual validation checklist
161instead.
162 
163## Reference Files
164 
165### Provider References
166 
167- `references/convex-auth.md`
168- `references/clerk.md`
169- `references/workos-authkit.md`
170- `references/auth0.md`
171 
172## Checklist
173 
174- [ ] Chosen the correct auth provider before writing setup code
175- [ ] Read the relevant provider reference file
176- [ ] Asked whether the user wants local-only setup or production-ready setup
177- [ ] Used the official provider docs for provider-specific wiring
178- [ ] Used the official Convex docs for shared auth behavior and authorization
179      patterns
180- [ ] Only added app-level user storage if the app actually needs it
181- [ ] Did not invent a cross-provider `users` table or `storeUser` flow for
182      Convex Auth
183- [ ] Added authentication checks in protected backend functions
184- [ ] Added authorization checks where the app actually needs them
185- [ ] Clear error messages ("Not authenticated", "Unauthorized")
186- [ ] Client auth provider configured for the chosen provider
187- [ ] If requested, production auth setup is covered too
188