1# Convex Auth
2 
3Official docs: https://docs.convex.dev/auth/convex-auth Setup guide:
4https://labs.convex.dev/auth/setup
5 
6Use this when the user wants auth handled directly in Convex rather than through
7a third-party provider.
8 
9## Workflow
10 
111. Confirm the user wants Convex Auth specifically
122. Determine which sign-in methods the app needs:
13   - magic links or OTPs
14   - OAuth providers
15   - passwords and password reset
163. Ask whether the user wants local-only setup or production-ready setup now
174. Read the Convex Auth setup guide before writing code
185. Make sure the project has a configured Convex deployment:
19   - run `npx convex dev` first if `CONVEX_DEPLOYMENT` is not set
20   - if CLI configuration requires interactive human input, stop and ask the
21     user to complete that step before continuing
226. Install the auth packages:
23   - `npm install @convex-dev/auth @auth/[email protected]`
247. Run the initialization command:
25   - `npx @convex-dev/auth`
268. Confirm the initializer created:
27   - `convex/auth.config.ts`
28   - `convex/auth.ts`
29   - `convex/http.ts`
309. Add the required `authTables` to `convex/schema.ts`
3110. Replace plain `ConvexProvider` wiring with `ConvexAuthProvider`
3211. Configure at least one auth method in `convex/auth.ts`
3312. Run `npx convex dev --once` or the normal dev flow to push the updated
34    schema and generated code
3513. Verify the client can sign in successfully
3614. Verify Convex receives authenticated identity in backend functions
3715. If the user wants production-ready setup, make sure the same auth setup is
38    configured for the production deployment as well
3916. Only add a `users` table and `storeUser` flow if the app needs app-level
40    user records inside Convex
41 
42## What This Reference Is For
43 
44- choosing Convex Auth as the default provider for a new Convex app
45- understanding whether the app wants magic links, OTPs, OAuth, or passwords
46- keeping the setup provider-specific while using the official Convex Auth docs
47  for identity and authorization behavior
48 
49## What To Do
50 
51- Read the Convex Auth setup guide before writing setup code
52- Follow the setup flow from the docs rather than recreating it from memory
53- If the app is new, consider starting from the official starter flow instead of
54  hand-wiring everything
55- Treat `npx @convex-dev/auth` as a required initialization step for existing
56  apps, not an optional extra
57 
58## Concrete Steps
59 
601. Install `@convex-dev/auth` and `@auth/[email protected]`
612. Run `npx convex dev` if the project does not already have a configured
62   deployment
633. If `npx convex dev` blocks on interactive setup, ask the user explicitly to
64   finish configuring the Convex deployment
654. Run `npx @convex-dev/auth`
665. Confirm the generated auth setup is present before continuing:
67   - `convex/auth.config.ts`
68   - `convex/auth.ts`
69   - `convex/http.ts`
706. Add `authTables` to `convex/schema.ts`
717. Replace `ConvexProvider` with `ConvexAuthProvider` in the app entry
728. Configure the selected auth methods in `convex/auth.ts`
739. Run `npx convex dev --once` or the normal dev flow so the updated schema and
74   auth files are pushed
7510. Verify login locally
7611. If the user wants production-ready setup, repeat the required auth
77    configuration against the production deployment
78 
79## Expected Files and Decisions
80 
81- `convex/schema.ts`
82- frontend app entry such as `src/main.tsx` or the framework-equivalent provider
83  file
84- generated Convex Auth setup produced by `npx @convex-dev/auth`
85- an existing configured Convex deployment, or the ability to create one with
86  `npx convex dev`
87- `convex/auth.ts` starts with `providers: []` until the app configures actual
88  sign-in methods
89 
90- Decide whether the user is creating a new app or adding auth to an existing
91  app
92- For a new app, prefer the official starter flow instead of rebuilding setup by
93  hand
94- Decide which auth methods the app needs:
95  - magic links or OTPs
96  - OAuth providers
97  - passwords
98- Decide whether the user wants local-only setup or production-ready setup now
99- Decide whether the app actually needs a `users` table inside Convex, or
100  whether provider identity alone is enough
101 
102## Gotchas
103 
104- Do not assume a specific sign-in method. Ask which methods the app needs
105  before wiring UI and backend behavior.
106- `npx @convex-dev/auth` is important because it initializes the auth setup,
107  including the key material. Do not skip it when adding Convex Auth to an
108  existing project.
109- `npx @convex-dev/auth` will fail if the project does not already have a
110  configured `CONVEX_DEPLOYMENT`.
111- `npx convex dev` may require interactive setup for deployment creation or
112  project selection. If that happens, ask the user explicitly for that human
113  step instead of guessing.
114- `npx @convex-dev/auth` does not finish the whole integration by itself. You
115  still need to add `authTables`, swap in `ConvexAuthProvider`, and configure at
116  least one auth method.
117- A project can still build even if `convex/auth.ts` still has `providers: []`,
118  so do not treat a successful build as proof that sign-in is fully configured.
119- Convex Auth does not mean every app needs a `users` table. If the app only
120  needs authentication gates, `ctx.auth.getUserIdentity()` may be enough.
121- If the app is greenfield, starting from the official starter flow is usually
122  better than partially recreating it by hand.
123- Do not stop at local dev setup if the user expects production-ready auth. The
124  production deployment needs the auth setup too.
125- Keep provider-specific setup and Convex Auth authorization behavior in the
126  official docs instead of inventing shared patterns from memory.
127 
128## Production
129 
130- Ask whether the user wants dev-only setup or production-ready setup
131- If the answer is production-ready, make sure the auth configuration is applied
132  to the production deployment, not just the dev deployment
133- Verify production-specific redirect URLs, auth method configuration, and
134  deployment settings before calling the task complete
135- Do not silently write a notes file into the repo by default. If the user wants
136  rollout or handoff docs, create one explicitly.
137 
138## Human Handoff
139 
140If `npx convex dev` or deployment setup requires human input:
141 
142- stop and explain exactly what the user needs to do
143- say why that step is required
144- resume the auth setup immediately after the user confirms it is done
145 
146## Validation
147 
148- Verify the user can complete a sign-in flow
149- Offer to validate sign up, sign out, and sign back in with the configured auth
150  method
151- If browser automation is available in the environment, you can do this
152  directly
153- If browser automation is not available, give the user a short manual
154  validation checklist instead
155- Verify `ctx.auth.getUserIdentity()` returns an identity in protected backend
156  functions
157- Verify protected UI only renders after Convex-authenticated state is ready
158- Verify environment variables and redirect settings match the current app
159  environment
160- Verify `convex/auth.ts` no longer has an empty `providers: []` configuration
161  once the app is meant to support real sign-in
162- Run `npx convex dev --once` or the normal dev flow after setup changes and
163  confirm Convex codegen and push succeed
164- If production-ready setup was requested, verify the production deployment is
165  also configured correctly
166 
167## Checklist
168 
169- [ ] Confirm the user wants Convex Auth specifically
170- [ ] Ask whether the user wants local-only setup or production-ready setup
171- [ ] Ensure a Convex deployment is configured before running auth
172      initialization
173- [ ] Install `@convex-dev/auth` and `@auth/[email protected]`
174- [ ] Run `npx convex dev` first if needed
175- [ ] Run `npx @convex-dev/auth`
176- [ ] Confirm `convex/auth.config.ts`, `convex/auth.ts`, and `convex/http.ts`
177      were created
178- [ ] Follow the setup guide for package install and wiring
179- [ ] Add `authTables` to `convex/schema.ts`
180- [ ] Replace `ConvexProvider` with `ConvexAuthProvider`
181- [ ] Configure at least one auth method in `convex/auth.ts`
182- [ ] Run `npx convex dev --once` or the normal dev flow after setup changes
183- [ ] Confirm which sign-in methods the app needs
184- [ ] Verify the client can sign in and the backend receives authenticated
185      identity
186- [ ] Offer end-to-end validation of sign up, sign out, and sign back in
187- [ ] If requested, configure the production deployment too
188- [ ] Only add extra `users` table sync if the app needs app-level user records
189