1# Auth0
2 
3Official docs:
4 
5- https://docs.convex.dev/auth/auth0
6- https://auth0.github.io/auth0-cli/
7- https://auth0.github.io/auth0-cli/auth0_apps_create.html
8 
9Use this when the app already uses Auth0 or the user wants Auth0 specifically.
10 
11## Workflow
12 
131. Confirm the user wants Auth0
142. Determine the app framework and whether Auth0 is already partly set up
153. Ask whether the user wants local-only setup or production-ready setup now
164. Read the official Convex and Auth0 guides before making changes
175. Ask whether they want the fastest setup path by installing the Auth0 CLI
186. If they agree, install the Auth0 CLI and do as much of the Auth0 app setup as
19   possible through the CLI
207. If they do not want the CLI path, use the Auth0 dashboard path instead
218. Complete the relevant Auth0 frontend quickstart if the app does not already
22   have Auth0 wired up
239. Configure `convex/auth.config.ts` with the Auth0 domain and client ID
2410. Set environment variables for local and production environments
2511. Wrap the app with `Auth0Provider` and `ConvexProviderWithAuth0`
2612. Gate Convex-backed UI with Convex auth state
2713. Try to verify Convex reports the user as authenticated after Auth0 login
2814. If the refresh-token path fails, stop improvising and send the user back to
29    the official docs
3015. If the user wants production-ready setup, make sure the production Auth0
31    tenant and env vars are also covered
32 
33## What To Do
34 
35- Read the official Convex and Auth0 guide before writing setup code
36- Prefer the Auth0 CLI path for mechanical setup if the user is willing to
37  install it, but do not present it as a fully validated end-to-end path yet
38- Ask the user directly: "The fastest path is to install the Auth0 CLI so I can
39  do more of this for you. If you want, I can install it and then only ask you
40  to log in when needed. Would you like me to do that?"
41- Make sure the app has already completed the relevant Auth0 quickstart for its
42  frontend
43- Use the official examples for `Auth0Provider` and `ConvexProviderWithAuth0`
44- If the Auth0 login or refresh flow starts failing in a way that is not clearly
45  explained by the docs, say that plainly and fall back to the official docs
46  instead of pretending the flow is validated
47 
48## Key Setup Areas
49 
50- install the Auth0 SDK for the app's framework
51- configure `convex/auth.config.ts` with the Auth0 domain and client ID
52- set environment variables for local and production environments
53- wrap the app with `Auth0Provider` and `ConvexProviderWithAuth0`
54- use Convex auth state when gating Convex-backed UI
55 
56## Files and Env Vars To Expect
57 
58- `convex/auth.config.ts`
59- frontend app entry or provider wrapper
60- Auth0 CLI install docs: `https://auth0.github.io/auth0-cli/`
61- Auth0 environment variables commonly include:
62  - `AUTH0_DOMAIN`
63  - `AUTH0_CLIENT_ID`
64  - `VITE_AUTH0_DOMAIN`
65  - `VITE_AUTH0_CLIENT_ID`
66 
67## Concrete Steps
68 
691. Start by reading `https://docs.convex.dev/auth/auth0` and the relevant Auth0
70   quickstart for the app's framework
712. Ask whether the user wants the Auth0 CLI path
723. If yes, install Auth0 CLI and have the user authenticate it with
73   `auth0 login`
744. Use `auth0 apps create` with SPA settings, callback URL, logout URL, and web
75   origins if creating a new app
765. If not using the CLI path, complete the relevant Auth0 frontend quickstart
77   and create the Auth0 app in the dashboard
786. Get the Auth0 domain and client ID from the CLI output or the Auth0 dashboard
797. Install the Auth0 SDK for the app's framework
808. Create or update `convex/auth.config.ts` with the Auth0 domain and client ID
819. Set frontend and backend environment variables
8210. Wrap the app in `Auth0Provider`
8311. Replace plain `ConvexProvider` wiring with `ConvexProviderWithAuth0`
8412. Run the normal Convex dev or deploy flow after backend config changes
8513. Try the official provider config shown in the Convex docs
8614. If login works but Convex auth or token refresh fails in a way you cannot
87    clearly resolve, stop and tell the user to follow the official docs manually
88    for now
8915. Only claim success if the user can sign in and Convex recognizes the
90    authenticated session
9116. If the user wants production-ready setup, configure the production Auth0
92    tenant values and production environment variables too
93 
94## Gotchas
95 
96- The Convex docs assume the Auth0 side is already set up, so do not skip the
97  Auth0 quickstart if the app is starting from scratch
98- The Auth0 CLI is often the fastest path for a fresh setup, but it still
99  requires the user to authenticate the CLI to their Auth0 tenant
100- If the user agrees to install the Auth0 CLI, do the mechanical setup yourself
101  instead of bouncing them through the dashboard
102- If login succeeds but Convex still reports unauthenticated, double-check
103  `convex/auth.config.ts` and whether the backend config was synced
104- We were able to automate Auth0 app creation and Convex config wiring, but we
105  did not fully validate the refresh-token path end to end
106- In validation, the documented `useRefreshTokens={true}` and
107  `cacheLocation="localstorage"` setup hit refresh-token failures, so do not
108  present that path as settled
109- If you hit Auth0 errors like `Unknown or invalid refresh token`, do not keep
110  inventing fixes indefinitely, send the user back to the official docs and
111  explain that this path is still under investigation
112- Keep dev and prod tenants separate if the project uses different Auth0
113  environments
114- Do not confuse "Auth0 login works" with "Convex can validate the Auth0 token".
115  Both need to work.
116- If the repo already uses Auth0, preserve existing redirect and tenant
117  configuration unless the user asked to change it.
118- Do not assume the local Auth0 tenant settings match production. Verify the
119  production domain, client ID, and callback URLs separately.
120- For local dev, make sure the Auth0 app settings match the app's real local
121  port for callback URLs, logout URLs, and web origins
122 
123## Production
124 
125- Ask whether the user wants dev-only setup or production-ready setup
126- If the answer is production-ready, make sure the production Auth0 tenant
127  values, callback URLs, and Convex deployment config are all covered
128- Verify production environment variables and redirect settings before calling
129  the task complete
130- Do not silently write a notes file into the repo by default. If the user wants
131  rollout or handoff docs, create one explicitly.
132 
133## Validation
134 
135- Verify the user can complete the Auth0 login flow
136- Verify Convex-authenticated UI renders only after Convex auth state is ready
137- Verify protected Convex queries succeed after login
138- Verify `ctx.auth.getUserIdentity()` is non-null in protected backend functions
139- Verify the Auth0 app settings match the real local callback and logout URLs
140  during development
141- If the Auth0 refresh-token path fails, mark the setup as not fully validated
142  and direct the user to the official docs instead of claiming the skill
143  completed successfully
144- If production-ready setup was requested, verify the production Auth0
145  configuration is also covered
146 
147## Checklist
148 
149- [ ] Confirm the user wants Auth0
150- [ ] Ask whether the user wants local-only setup or production-ready setup
151- [ ] Complete the relevant Auth0 frontend setup
152- [ ] Configure `convex/auth.config.ts`
153- [ ] Set environment variables
154- [ ] Verify Convex authenticated state after login, or explicitly tell the user
155      this path is still under investigation and send them to the official docs
156- [ ] If requested, configure the production deployment too
157