AuthKit and Convex configuration issue

[elder frost]

Hi @primal kelp. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

The knowledge sources don’t include your specific code or callback implementation, so I can’t pinpoint the exact bug. But they do describe several production-only failure modes for WorkOS AuthKit + Convex that match what you’re seeing (dev works, prod never becomes authenticated). Here are the concrete things to check, all based on those sources:

1. Make sure Convex’s auth config is correct in prod and deployed

   Your convex/auth.config.ts for WorkOS AuthKit should look like this (or very close): [AuthKit config]

   const clientId = process.env.WORKOS_CLIENT_ID;
   
   export default {
     providers: [
       {
         type: "customJwt",
         issuer: `<https://api.workos.com/`,>
         algorithm: "RS256",
         applicationID: clientId,
         jwks: `<https://api.workos.com/sso/jwks/${clientId}`,>
       },
       {
         type: "customJwt",
         issuer: `<https://api.workos.com/user_management/${clientId}`,>
         algorithm: "RS256",
         jwks: `<https://api.workos.com/sso/jwks/${clientId}`,>
         // IMPORTANT: no applicationID here
       },
     ],
   };
   

   Two common gotchas:

   • Using the wrong WORKOS_CLIENT_ID for production (still pointing at your dev app). [AuthKit debugging]
   • Leaving applicationID on the second provider; this is known to break auth and cause getUserIdentity() / isAuthenticated to fail. [Missing aud / appID]

   After changing auth.config.ts, you must run npx convex deploy so the production deployment picks up the new config. [AuthKit config]

2. Verify prod environment variables on both Convex and your host

   For production you need, at minimum: [AuthKit config]

   On Convex dashboard → production deployment:

   • WORKOS_CLIENT_ID="client_01... (prod app)"

   On your frontend/backend host (e.g. Vercel):

   • WORKOS_CLIENT_ID="client_01... (prod app)"
   • WORKOS_API_KEY="sk_live_..."
   • WORKOS_COOKIE_PASSWORD="at_least_32_chars"
   • NEXT_PUBLIC_WORKOS_REDIRECT_URI="<https://your-domain.com/callback">

   If any of these still point at dev values, AuthKit will succeed locally but Convex will reject the token in prod.

3. Check the redirect / callback URI

   The redirect URI must match exactly between:

   • NEXT_PUBLIC_WORKOS_REDIRECT_URI in your prod env
   • The callback URL configured in the WorkOS Dashboard for your production app [AuthKit config]

   If the callback is wrong, WorkOS may still set a session cookie, but the AuthKit client and Convex won’t line up and isAuthenticated will stay false.

4. Confirm the JWT has the required aud claim in prod

   Convex requires an aud claim on the JWT. WorkOS may not include it by default. [AuthKit debugging]

   • In the WorkOS Dashboard, check your JWT template / configuration and ensure aud is set to your Client ID.
   • If dev and prod use different WorkOS apps, make sure the prod app’s JWT config is also updated.

   Missing aud is a documented cause of ctx.auth.getUserIdentity() returning null and isAuthenticated staying false. [AuthKit debugging]

5. Double‑check the WorkOS → Convex issuer / JWKS URLs

   For AuthKit, Convex should be validating against WorkOS’s JWKS endpoint:

   • issuer should be exactly <https://api.workos.com/> or <https://api.workos.com/user_management/${clientId}> (no extra slashes or wrong client IDs). [AuthKit config]
   • jwks should be <https://api.workos.com/sso/jwks/${clientId}.>

   If you changed these for prod (e.g. custom domain, proxy, or different JWKS URL), Convex may not find a matching provider and will silently treat the user as unauthenticated. [AuthKit debugging]

6. Compare with a fresh template / testbed

   Support has recommended starting from the official template or testbed to compare a known‑good setup: [WorkOS/Convex thread]

   • Clone workos/template-convex-nextjs-authkit or the Convex testbed and wire it to your production WorkOS app.
   • If that works in prod, diff its auth.config.ts, env vars, and callback route against your app.

---

If you’d like, paste:

• Your convex/auth.config.ts
• The relevant env vars (with secrets redacted)
• The callback route code / URL you’re using in prod

and I can map them directly against the patterns above using the docs.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@primal kelp Kapa.ai is still learning and improving, please let me know how I did by reacting below.