1# WorkOS AuthKit
2 
3Official docs:
4 
5- https://docs.convex.dev/auth/authkit/
6- https://docs.convex.dev/auth/authkit/add-to-app
7- https://docs.convex.dev/auth/authkit/auto-provision
8 
9Use this when the app already uses WorkOS or the user wants AuthKit
10specifically.
11 
12## Workflow
13 
141. Confirm the user wants WorkOS AuthKit
152. Determine whether they want:
16   - a Convex-managed WorkOS team
17   - an existing WorkOS team
183. Ask whether the user wants local-only setup or production-ready setup now
194. Read the official Convex and WorkOS AuthKit guide
205. Create or update `convex.json` for the app's framework and real local port
216. Follow the correct branch of the setup flow based on that choice
227. Configure the required WorkOS environment variables
238. Configure `convex/auth.config.ts` for WorkOS-issued JWTs
249. Wire the client provider and callback flow
2510. Verify authenticated requests reach Convex
2611. If the user wants production-ready setup, make sure the production WorkOS
27    configuration is covered too
2812. Only add `storeUser` or a `users` table if the app needs first-class user
29    rows inside Convex
30 
31## What To Do
32 
33- Read the official Convex and WorkOS AuthKit guide before writing setup code
34- Determine whether the user wants a Convex-managed WorkOS team or an existing
35  WorkOS team
36- Treat `convex.json` as a first-class part of the AuthKit setup, not an
37  optional extra
38- Follow the current setup flow from the docs instead of relying on older
39  examples
40 
41## Key Setup Areas
42 
43- package installation for the app's framework
44- `convex.json` with the `authKit` section for dev, and preview or prod if
45  needed
46- environment variables such as `WORKOS_CLIENT_ID`, `WORKOS_API_KEY`, and
47  redirect configuration
48- `convex/auth.config.ts` wiring for WorkOS-issued JWTs
49- client provider setup and token flow into Convex
50- login callback and redirect configuration
51 
52## Files and Env Vars To Expect
53 
54- `convex.json`
55- `convex/auth.config.ts`
56- frontend auth provider wiring
57- callback or redirect route setup where the framework requires it
58- WorkOS environment variables commonly include:
59  - `WORKOS_CLIENT_ID`
60  - `WORKOS_API_KEY`
61  - `WORKOS_COOKIE_PASSWORD`
62  - `VITE_WORKOS_CLIENT_ID`
63  - `VITE_WORKOS_REDIRECT_URI`
64  - `NEXT_PUBLIC_WORKOS_REDIRECT_URI`
65 
66For a managed WorkOS team, `convex dev` can provision the AuthKit environment
67and write local env vars such as `VITE_WORKOS_CLIENT_ID` and
68`VITE_WORKOS_REDIRECT_URI` into `.env.local` for Vite apps.
69 
70## Concrete Steps
71 
721. Choose Convex-managed or existing WorkOS team
732. Create or update `convex.json` with the `authKit` section for the framework
74   in use
753. Make sure the dev `redirectUris`, `appHomepageUrl`, `corsOrigins`, and local
76   redirect env vars match the app's actual local port
774. For a managed WorkOS team, run `npx convex dev` and follow the interactive
78   onboarding flow
795. For an existing WorkOS team, get `WORKOS_CLIENT_ID` and `WORKOS_API_KEY` from
80   the WorkOS dashboard and set them with `npx convex env set`
816. Create or update `convex/auth.config.ts` for WorkOS JWT validation
827. Run the normal Convex dev or deploy flow so backend config is synced
838. Wire the WorkOS client provider in the app
849. Configure callback and redirect handling
8510. Verify the user can sign in and return to the app
8611. Verify Convex sees the authenticated user after login
8712. If the user wants production-ready setup, configure the production client
88    ID, API key, redirect URI, and deployment settings too
89 
90## Gotchas
91 
92- The docs split setup between Convex-managed and existing WorkOS teams, so ask
93  which path the user wants if it is not obvious
94- Keep dev and prod WorkOS configuration separate where the docs call for
95  different client IDs or API keys
96- Only add `storeUser` or a `users` table if the app needs first-class user rows
97  inside Convex
98- Do not mix dev and prod WorkOS credentials or redirect URIs
99- If the repo already contains WorkOS setup, preserve the current tenant model
100  unless the user wants to change it
101- For managed WorkOS setup, `convex dev` is interactive the first time. In
102  non-interactive terminals, stop and ask the user to complete the onboarding
103  prompts.
104- `convex.json` is not optional for the managed AuthKit flow. It drives redirect
105  URI, homepage URL, CORS configuration, and local env var generation.
106- If the frontend starts on a different port than the one in `convex.json`, the
107  hosted WorkOS sign-in flow will point to the wrong callback URL. Update
108  `convex.json`, update the local redirect env var, and run `npx convex dev`
109  again.
110- Vite can fall off `5173` if other apps are already running. Do not assume the
111  default port still matches the generated AuthKit config.
112- A successful WorkOS sign-in should redirect back to the local callback route
113  and then reach a Convex-authenticated state. Do not stop at "the hosted WorkOS
114  page loaded."
115 
116## Production
117 
118- Ask whether the user wants dev-only setup or production-ready setup
119- If the answer is production-ready, make sure the production WorkOS client ID,
120  API key, redirect URI, and Convex deployment config are all covered
121- Verify the production redirect and callback settings before calling the task
122  complete
123- Do not silently write a notes file into the repo by default. If the user wants
124  rollout or handoff docs, create one explicitly.
125 
126## Validation
127 
128- Verify the user can complete the login flow and return to the app
129- Verify the callback URL matches the real frontend port in local dev
130- Verify Convex receives authenticated requests after login
131- Verify `convex.json` matches the framework and chosen WorkOS setup path
132- Verify `convex/auth.config.ts` matches the chosen WorkOS setup path
133- Verify environment variables differ correctly between local and production
134  where needed
135- If production-ready setup was requested, verify the production WorkOS
136  configuration is also covered
137 
138## Checklist
139 
140- [ ] Confirm the user wants WorkOS AuthKit
141- [ ] Ask whether the user wants local-only setup or production-ready setup
142- [ ] Choose Convex-managed or existing WorkOS team
143- [ ] Create or update `convex.json`
144- [ ] Configure WorkOS environment variables
145- [ ] Configure `convex/auth.config.ts`
146- [ ] Verify authenticated requests reach Convex after login
147- [ ] If requested, configure the production deployment too
148