Convex Setup Auth

Convex Authentication Setup

Implement secure authentication in Convex with user management and access control.

When to Use

• Setting up authentication for the first time
• Implementing user management (users table, identity mapping)
• Creating authentication helper functions
• Setting up auth providers (Convex Auth, Clerk, WorkOS AuthKit, Auth0, custom

JWT)

When Not to Use

• Auth for a non-Convex backend
• Pure OAuth/OIDC documentation without a Convex implementation
• Debugging unrelated bugs that happen to surface near auth code
• The auth provider is already fully configured and the user only needs a

one-line fix

First Step: Choose the Auth Provider

Convex supports multiple authentication approaches. Do not assume a provider.

Before writing setup code:

1. Ask the user which auth solution they want, unless the repository already makes it obvious 2. If the repo already uses a provider, continue with that provider unless the user wants to switch 3. If the user has not chosen a provider and the repo does not make it obvious, ask before proceeding

Common options:

• Convex Auth - good default when

the user wants auth handled directly in Convex

• Clerk - use when the app already uses

Clerk or the user wants Clerk's hosted auth features

• WorkOS AuthKit - use when the app

already uses WorkOS or the user wants AuthKit specifically

• Auth0 - use when the app already uses

Auth0

• Custom JWT provider - use when integrating an existing auth system not covered

above

Look for signals in the repo before asking:

• Dependencies such as @clerk/*, @workos-inc/*, @auth0/*, or Convex Auth

packages

• Existing files such as convex/auth.config.ts, auth middleware, provider

wrappers, or login components

• Environment variables that clearly point at a provider

After Choosing a Provider

Read the provider's official guide and the matching local reference file:

• Convex Auth: official docs, then

references/convex-auth.md

• Clerk: official docs, then

references/clerk.md

• WorkOS AuthKit: official docs, then

references/workos-authkit.md

• Auth0: official docs, then

references/auth0.md

The local reference files contain the concrete workflow, expected files and env vars, gotchas, and validation checks.

Use those sources for:

• package installation
• client provider wiring
• environment variables
• convex/auth.config.ts setup
• login and logout UI patterns
• framework-specific setup for React, Vite, or Next.js

For shared auth behavior, use the official Convex docs as the source of truth:

• Auth in Functions for

ctx.auth.getUserIdentity()

• Storing Users in the Convex Database

for optional app-level user storage

• Authentication for general auth and

authorization guidance

• Convex Auth Authorization when the

provider is Convex Auth

Prefer official docs over recalled steps, because provider CLIs and Convex Auth internals change between versions. Inventing setup from memory risks outdated patterns. For third-party providers, only add app-level user storage if the app actually needs user documents in Convex. Not every app needs a users table. For Convex Auth, follow the Convex Auth docs and built-in auth tables rather than adding a parallel users table plus storeUser flow, because Convex Auth already manages user records internally. After running provider initialization commands, verify generated files and complete the post-init wiring steps the provider reference calls out. Initialization commands rarely finish the entire integration.

Core Pattern: Protecting Backend Functions

The most common auth task is checking identity in Convex functions.

// Bad: trusting a client-provided userId
export const getMyProfile = query({
  args: { userId: v.id("users") },
  handler: async (ctx, args) => {
    return await ctx.db.get(args.userId);
  },
});

// Good: verifying identity server-side
export const getMyProfile = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    return await ctx.db
      .query("users")
      .withIndex("by_tokenIdentifier", (q) =>
        q.eq("tokenIdentifier", identity.tokenIdentifier),
      )
      .unique();
  },
});

Workflow

1. Determine the provider, either by asking the user or inferring from the repo 2. Ask whether the user wants local-only setup or production-ready setup now 3. Read the matching provider reference file 4. Follow the official provider docs for current setup details 5. Follow the official Convex docs for shared backend auth behavior, user storage, and authorization patterns 6. Only add app-level user storage if the docs and app requirements call for it 7. Add authorization checks for ownership, roles, or team access only where the app needs them 8. Verify login state, protected queries, environment variables, and production configuration if requested

If the flow blocks on interactive provider or deployment setup, ask the user explicitly for the exact human step needed, then continue after they complete it. For UI-facing auth flows, offer to validate the real sign-up or sign-in flow after setup is done. If the environment has browser automation tools, you can use them. If it does not, give the user a short manual validation checklist instead.

Reference Files

Provider References

• references/convex-auth.md
• references/clerk.md
• references/workos-authkit.md
• references/auth0.md

Checklist

• [ ] Chosen the correct auth provider before writing setup code
• [ ] Read the relevant provider reference file
• [ ] Asked whether the user wants local-only setup or production-ready setup
• [ ] Used the official provider docs for provider-specific wiring
• [ ] Used the official Convex docs for shared auth behavior and authorization

patterns

• [ ] Only added app-level user storage if the app actually needs it
• [ ] Did not invent a cross-provider users table or storeUser flow for

Convex Auth

• [ ] Added authentication checks in protected backend functions
• [ ] Added authorization checks where the app actually needs them
• [ ] Clear error messages ("Not authenticated", "Unauthorized")
• [ ] Client auth provider configured for the chosen provider
• [ ] If requested, production auth setup is covered too

Auth0

Official docs:

• https://docs.convex.dev/auth/auth0
• https://auth0.github.io/auth0-cli/
• https://auth0.github.io/auth0-cli/auth0_apps_create.html

Use this when the app already uses Auth0 or the user wants Auth0 specifically.

Workflow

1. Confirm the user wants Auth0 2. Determine the app framework and whether Auth0 is already partly set up 3. Ask whether the user wants local-only setup or production-ready setup now 4. Read the official Convex and Auth0 guides before making changes 5. Ask whether they want the fastest setup path by installing the Auth0 CLI 6. If they agree, install the Auth0 CLI and do as much of the Auth0 app setup as possible through the CLI 7. If they do not want the CLI path, use the Auth0 dashboard path instead 8. Complete the relevant Auth0 frontend quickstart if the app does not already have Auth0 wired up 9. Configure convex/auth.config.ts with the Auth0 domain and client ID 10. Set environment variables for local and production environments 11. Wrap the app with Auth0Provider and ConvexProviderWithAuth0 12. Gate Convex-backed UI with Convex auth state 13. Try to verify Convex reports the user as authenticated after Auth0 login 14. If the refresh-token path fails, stop improvising and send the user back to the official docs 15. If the user wants production-ready setup, make sure the production Auth0 tenant and env vars are also covered

What To Do

• Read the official Convex and Auth0 guide before writing setup code
• Prefer the Auth0 CLI path for mechanical setup if the user is willing to

install it, but do not present it as a fully validated end-to-end path yet

• Ask the user directly: "The fastest path is to install the Auth0 CLI so I can

do more of this for you. If you want, I can install it and then only ask you to log in when needed. Would you like me to do that?"

• Make sure the app has already completed the relevant Auth0 quickstart for its

frontend

• Use the official examples for Auth0Provider and ConvexProviderWithAuth0
• If the Auth0 login or refresh flow starts failing in a way that is not clearly

explained by the docs, say that plainly and fall back to the official docs instead of pretending the flow is validated

Key Setup Areas

• install the Auth0 SDK for the app's framework
• configure convex/auth.config.ts with the Auth0 domain and client ID
• set environment variables for local and production environments
• wrap the app with Auth0Provider and ConvexProviderWithAuth0
• use Convex auth state when gating Convex-backed UI

Files and Env Vars To Expect

• convex/auth.config.ts
• frontend app entry or provider wrapper
• Auth0 CLI install docs: https://auth0.github.io/auth0-cli/
• Auth0 environment variables commonly include:
• AUTH0_DOMAIN
• AUTH0_CLIENT_ID
• VITE_AUTH0_DOMAIN
• VITE_AUTH0_CLIENT_ID

Concrete Steps

1. Start by reading https://docs.convex.dev/auth/auth0 and the relevant Auth0 quickstart for the app's framework 2. Ask whether the user wants the Auth0 CLI path 3. If yes, install Auth0 CLI and have the user authenticate it with auth0 login 4. Use auth0 apps create with SPA settings, callback URL, logout URL, and web origins if creating a new app 5. If not using the CLI path, complete the relevant Auth0 frontend quickstart and create the Auth0 app in the dashboard 6. Get the Auth0 domain and client ID from the CLI output or the Auth0 dashboard 7. Install the Auth0 SDK for the app's framework 8. Create or update convex/auth.config.ts with the Auth0 domain and client ID 9. Set frontend and backend environment variables 10. Wrap the app in Auth0Provider 11. Replace plain ConvexProvider wiring with ConvexProviderWithAuth0 12. Run the normal Convex dev or deploy flow after backend config changes 13. Try the official provider config shown in the Convex docs 14. If login works but Convex auth or token refresh fails in a way you cannot clearly resolve, stop and tell the user to follow the official docs manually for now 15. Only claim success if the user can sign in and Convex recognizes the authenticated session 16. If the user wants production-ready setup, configure the production Auth0 tenant values and production environment variables too

Gotchas

• The Convex docs assume the Auth0 side is already set up, so do not skip the

Auth0 quickstart if the app is starting from scratch

• The Auth0 CLI is often the fastest path for a fresh setup, but it still

requires the user to authenticate the CLI to their Auth0 tenant

• If the user agrees to install the Auth0 CLI, do the mechanical setup yourself

instead of bouncing them through the dashboard

• If login succeeds but Convex still reports unauthenticated, double-check

convex/auth.config.ts and whether the backend config was synced

• We were able to automate Auth0 app creation and Convex config wiring, but we

did not fully validate the refresh-token path end to end

• In validation, the documented useRefreshTokens={true} and

cacheLocation="localstorage" setup hit refresh-token failures, so do not present that path as settled

• If you hit Auth0 errors like Unknown or invalid refresh token, do not keep

inventing fixes indefinitely, send the user back to the official docs and explain that this path is still under investigation

• Keep dev and prod tenants separate if the project uses different Auth0

environments

• Do not confuse "Auth0 login works" with "Convex can validate the Auth0 token".

Both need to work.

• If the repo already uses Auth0, preserve existing redirect and tenant

configuration unless the user asked to change it.

• Do not assume the local Auth0 tenant settings match production. Verify the

production domain, client ID, and callback URLs separately.

• For local dev, make sure the Auth0 app settings match the app's real local

port for callback URLs, logout URLs, and web origins

Production

• Ask whether the user wants dev-only setup or production-ready setup
• If the answer is production-ready, make sure the production Auth0 tenant

values, callback URLs, and Convex deployment config are all covered

• Verify production environment variables and redirect settings before calling

the task complete

• Do not silently write a notes file into the repo by default. If the user wants

rollout or handoff docs, create one explicitly.

Validation

• Verify the user can complete the Auth0 login flow
• Verify Convex-authenticated UI renders only after Convex auth state is ready
• Verify protected Convex queries succeed after login
• Verify ctx.auth.getUserIdentity() is non-null in protected backend functions
• Verify the Auth0 app settings match the real local callback and logout URLs

during development

• If the Auth0 refresh-token path fails, mark the setup as not fully validated

and direct the user to the official docs instead of claiming the skill completed successfully

• If production-ready setup was requested, verify the production Auth0

configuration is also covered

Checklist

• [ ] Confirm the user wants Auth0
• [ ] Ask whether the user wants local-only setup or production-ready setup
• [ ] Complete the relevant Auth0 frontend setup
• [ ] Configure convex/auth.config.ts
• [ ] Set environment variables
• [ ] Verify Convex authenticated state after login, or explicitly tell the user

this path is still under investigation and send them to the official docs

• [ ] If requested, configure the production deployment too

Clerk

Official docs:

• https://docs.convex.dev/auth/clerk
• https://clerk.com/docs/guides/development/integrations/databases/convex

Use this when the app already uses Clerk or the user wants Clerk's hosted auth features.

Workflow

1. Confirm the user wants Clerk 2. Make sure the user has a Clerk account and a Clerk application 3. Determine the app framework:

• React
• Next.js
• TanStack Start

4. Ask whether the user wants local-only setup or production-ready setup now 5. Gather the Clerk keys and the Clerk Frontend API URL 6. Follow the correct framework section in the official docs 7. Complete the backend and client wiring 8. Verify Convex reports the user as authenticated after login 9. If the user wants production-ready setup, make sure the production Clerk config is also covered

What To Do

• Read the official Convex and Clerk guide before writing setup code
• If the user does not already have Clerk set up, send them to

https://dashboard.clerk.com/sign-up to create an account and https://dashboard.clerk.com/apps/new to create an application

• Send the user to https://dashboard.clerk.com/apps/setup/convex if the Convex

integration is not already active

• Match the guide to the app's framework, usually React, Next.js, or TanStack

Start

• Use the official examples for ConvexProviderWithClerk, ClerkProvider, and

useAuth

Key Setup Areas

• install the Clerk SDK for the framework in use
• configure convex/auth.config.ts with the Clerk issuer domain
• set the required Clerk environment variables
• wrap the app with ClerkProvider and ConvexProviderWithClerk
• use Convex auth-aware UI patterns such as Authenticated, Unauthenticated,

and AuthLoading

Files and Env Vars To Expect

• convex/auth.config.ts
• React or Vite client entry such as src/main.tsx
• Next.js client wrapper for Convex if using App Router
• Clerk account sign-up page: https://dashboard.clerk.com/sign-up
• Clerk app creation page: https://dashboard.clerk.com/apps/new
• Clerk Convex integration page: https://dashboard.clerk.com/apps/setup/convex
• Clerk API keys page: https://dashboard.clerk.com/last-active?path=api-keys
• Clerk environment variables:
• CLERK_JWT_ISSUER_DOMAIN for Convex backend validation in the Convex docs
• CLERK_FRONTEND_API_URL in the Clerk docs
• VITE_CLERK_PUBLISHABLE_KEY for Vite apps
• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY for Next.js apps
• CLERK_SECRET_KEY for Next.js server-side Clerk setup where required

CLERK_JWT_ISSUER_DOMAIN and CLERK_FRONTEND_API_URL refer to the same Clerk Frontend API URL value. Do not treat them as two different URLs.

Concrete Steps

1. If needed, create a Clerk account at https://dashboard.clerk.com/sign-up 2. If needed, create a Clerk application at https://dashboard.clerk.com/apps/new 3. Open https://dashboard.clerk.com/last-active?path=api-keys and copy the publishable key, plus the secret key for Next.js where needed 4. Open https://dashboard.clerk.com/apps/setup/convex 5. Activate the Convex integration in Clerk if it is not already active 6. Copy the Clerk Frontend API URL shown there 7. Install the Clerk package for the app's framework 8. Create or update convex/auth.config.ts so Convex validates Clerk tokens 9. Set the publishable key in the frontend environment 10. Set the issuer domain or Frontend API URL so Convex can validate the JWT 11. Replace plain ConvexProvider wiring with ConvexProviderWithClerk 12. Wrap the app in ClerkProvider 13. Use Convex auth helpers for authenticated rendering 14. Run the normal Convex dev or deploy flow after updating backend auth config 15. If the user wants production-ready setup, configure the production Clerk values and production issuer domain too

Gotchas

• Prefer useConvexAuth() over raw Clerk auth state when deciding whether

Convex-authenticated UI can render

• For Next.js, keep server and client boundaries in mind when creating the

Convex provider wrapper

• After changing convex/auth.config.ts, run the normal Convex dev or deploy

flow so the backend picks up the new config

• Do not stop at "Clerk login works". The important check is that Convex also

sees the session and can authenticate requests.

• If the repo already uses Clerk, preserve its existing auth flow unless the

user asked to change it.

• Do not assume the same Clerk values work for both dev and production. Check

the production issuer domain and publishable key separately.

• The Convex setup page is where you get the Clerk Frontend API URL for Convex.

Keep using the Clerk API keys page for the publishable key and the secret key.

• If Convex says no auth provider matched the token, first confirm the Clerk

Convex integration was activated at https://dashboard.clerk.com/apps/setup/convex

• After activating the Clerk Convex integration, sign out completely and sign

back in before retesting. An old Clerk session can keep using a token that Convex rejects.

Production

• Ask whether the user wants dev-only setup or production-ready setup
• If the answer is production-ready, make sure production Clerk keys and issuer

configuration are included

• Verify production redirect URLs and any production Clerk domain values before

calling the task complete

• Do not silently write a notes file into the repo by default. If the user wants

rollout or handoff docs, create one explicitly.

Validation

• Verify the user can sign in with Clerk
• If the Clerk integration was just activated, verify after a full Clerk

sign-out and fresh sign-in

• Verify useConvexAuth() reaches the authenticated state after Clerk login
• Verify protected Convex queries run successfully inside authenticated UI
• Verify ctx.auth.getUserIdentity() is non-null in protected backend functions
• If production-ready setup was requested, verify the production Clerk

configuration is also covered

Checklist

• [ ] Confirm the user wants Clerk
• [ ] Ask whether the user wants local-only setup or production-ready setup
• [ ] Follow the correct framework section in the official guide
• [ ] Set Clerk environment variables
• [ ] Configure convex/auth.config.ts
• [ ] Verify Convex authenticated state after login
• [ ] If requested, configure the production deployment too

Convex Auth

Official docs: https://docs.convex.dev/auth/convex-auth Setup guide: https://labs.convex.dev/auth/setup

Use this when the user wants auth handled directly in Convex rather than through a third-party provider.

Workflow

1. Confirm the user wants Convex Auth specifically 2. Determine which sign-in methods the app needs:

• magic links or OTPs
• OAuth providers
• passwords and password reset

3. Ask whether the user wants local-only setup or production-ready setup now 4. Read the Convex Auth setup guide before writing code 5. Make sure the project has a configured Convex deployment:

• run npx convex dev first if CONVEX_DEPLOYMENT is not set
• if CLI configuration requires interactive human input, stop and ask the

user to complete that step before continuing 6. Install the auth packages:

• npm install @convex-dev/auth @auth/core@0.37.0

7. Run the initialization command:

• npx @convex-dev/auth

8. Confirm the initializer created:

• convex/auth.config.ts
• convex/auth.ts
• convex/http.ts

9. Add the required authTables to convex/schema.ts 10. Replace plain ConvexProvider wiring with ConvexAuthProvider 11. Configure at least one auth method in convex/auth.ts 12. Run npx convex dev --once or the normal dev flow to push the updated schema and generated code 13. Verify the client can sign in successfully 14. Verify Convex receives authenticated identity in backend functions 15. If the user wants production-ready setup, make sure the same auth setup is configured for the production deployment as well 16. Only add a users table and storeUser flow if the app needs app-level user records inside Convex

What This Reference Is For

• choosing Convex Auth as the default provider for a new Convex app
• understanding whether the app wants magic links, OTPs, OAuth, or passwords
• keeping the setup provider-specific while using the official Convex Auth docs

for identity and authorization behavior

What To Do

• Read the Convex Auth setup guide before writing setup code
• Follow the setup flow from the docs rather than recreating it from memory
• If the app is new, consider starting from the official starter flow instead of

hand-wiring everything

• Treat npx @convex-dev/auth as a required initialization step for existing

apps, not an optional extra

Concrete Steps

1. Install @convex-dev/auth and @auth/core@0.37.0 2. Run npx convex dev if the project does not already have a configured deployment 3. If npx convex dev blocks on interactive setup, ask the user explicitly to finish configuring the Convex deployment 4. Run npx @convex-dev/auth 5. Confirm the generated auth setup is present before continuing:

• convex/auth.config.ts
• convex/auth.ts
• convex/http.ts

6. Add authTables to convex/schema.ts 7. Replace ConvexProvider with ConvexAuthProvider in the app entry 8. Configure the selected auth methods in convex/auth.ts 9. Run npx convex dev --once or the normal dev flow so the updated schema and auth files are pushed 10. Verify login locally 11. If the user wants production-ready setup, repeat the required auth configuration against the production deployment

Expected Files and Decisions

• convex/schema.ts
• frontend app entry such as src/main.tsx or the framework-equivalent provider

file

• generated Convex Auth setup produced by npx @convex-dev/auth
• an existing configured Convex deployment, or the ability to create one with

npx convex dev

• convex/auth.ts starts with providers: [] until the app configures actual

sign-in methods

• Decide whether the user is creating a new app or adding auth to an existing

app

• For a new app, prefer the official starter flow instead of rebuilding setup by

hand

• Decide which auth methods the app needs:
• magic links or OTPs
• OAuth providers
• passwords
• Decide whether the user wants local-only setup or production-ready setup now
• Decide whether the app actually needs a users table inside Convex, or

whether provider identity alone is enough

Gotchas

• Do not assume a specific sign-in method. Ask which methods the app needs

before wiring UI and backend behavior.

• npx @convex-dev/auth is important because it initializes the auth setup,

including the key material. Do not skip it when adding Convex Auth to an existing project.

• npx @convex-dev/auth will fail if the project does not already have a

configured CONVEX_DEPLOYMENT.

• npx convex dev may require interactive setup for deployment creation or

project selection. If that happens, ask the user explicitly for that human step instead of guessing.

• npx @convex-dev/auth does not finish the whole integration by itself. You

still need to add authTables, swap in ConvexAuthProvider, and configure at least one auth method.

• A project can still build even if convex/auth.ts still has providers: [],

so do not treat a successful build as proof that sign-in is fully configured.

• Convex Auth does not mean every app needs a users table. If the app only

needs authentication gates, ctx.auth.getUserIdentity() may be enough.

• If the app is greenfield, starting from the official starter flow is usually

better than partially recreating it by hand.

• Do not stop at local dev setup if the user expects production-ready auth. The

production deployment needs the auth setup too.

• Keep provider-specific setup and Convex Auth authorization behavior in the

official docs instead of inventing shared patterns from memory.

Production

• Ask whether the user wants dev-only setup or production-ready setup
• If the answer is production-ready, make sure the auth configuration is applied

to the production deployment, not just the dev deployment

• Verify production-specific redirect URLs, auth method configuration, and

deployment settings before calling the task complete

• Do not silently write a notes file into the repo by default. If the user wants

rollout or handoff docs, create one explicitly.

Human Handoff

If npx convex dev or deployment setup requires human input:

• stop and explain exactly what the user needs to do
• say why that step is required
• resume the auth setup immediately after the user confirms it is done

Validation

• Verify the user can complete a sign-in flow
• Offer to validate sign up, sign out, and sign back in with the configured auth

method

• If browser automation is available in the environment, you can do this

directly

• If browser automation is not available, give the user a short manual

validation checklist instead

• Verify ctx.auth.getUserIdentity() returns an identity in protected backend

functions

• Verify protected UI only renders after Convex-authenticated state is ready
• Verify environment variables and redirect settings match the current app

environment

• Verify convex/auth.ts no longer has an empty providers: [] configuration

once the app is meant to support real sign-in

• Run npx convex dev --once or the normal dev flow after setup changes and

confirm Convex codegen and push succeed

• If production-ready setup was requested, verify the production deployment is

also configured correctly

Checklist

• [ ] Confirm the user wants Convex Auth specifically
• [ ] Ask whether the user wants local-only setup or production-ready setup
• [ ] Ensure a Convex deployment is configured before running auth

initialization

• [ ] Install @convex-dev/auth and @auth/core@0.37.0
• [ ] Run npx convex dev first if needed
• [ ] Run npx @convex-dev/auth
• [ ] Confirm convex/auth.config.ts, convex/auth.ts, and convex/http.ts

were created

• [ ] Follow the setup guide for package install and wiring
• [ ] Add authTables to convex/schema.ts
• [ ] Replace ConvexProvider with ConvexAuthProvider
• [ ] Configure at least one auth method in convex/auth.ts
• [ ] Run npx convex dev --once or the normal dev flow after setup changes
• [ ] Confirm which sign-in methods the app needs
• [ ] Verify the client can sign in and the backend receives authenticated

identity

• [ ] Offer end-to-end validation of sign up, sign out, and sign back in
• [ ] If requested, configure the production deployment too
• [ ] Only add extra users table sync if the app needs app-level user records

WorkOS AuthKit

Official docs:

• https://docs.convex.dev/auth/authkit/
• https://docs.convex.dev/auth/authkit/add-to-app
• https://docs.convex.dev/auth/authkit/auto-provision

Use this when the app already uses WorkOS or the user wants AuthKit specifically.

Workflow

1. Confirm the user wants WorkOS AuthKit 2. Determine whether they want:

• a Convex-managed WorkOS team
• an existing WorkOS team

3. Ask whether the user wants local-only setup or production-ready setup now 4. Read the official Convex and WorkOS AuthKit guide 5. Create or update convex.json for the app's framework and real local port 6. Follow the correct branch of the setup flow based on that choice 7. Configure the required WorkOS environment variables 8. Configure convex/auth.config.ts for WorkOS-issued JWTs 9. Wire the client provider and callback flow 10. Verify authenticated requests reach Convex 11. If the user wants production-ready setup, make sure the production WorkOS configuration is covered too 12. Only add storeUser or a users table if the app needs first-class user rows inside Convex

What To Do

• Read the official Convex and WorkOS AuthKit guide before writing setup code
• Determine whether the user wants a Convex-managed WorkOS team or an existing

WorkOS team

• Treat convex.json as a first-class part of the AuthKit setup, not an

optional extra

• Follow the current setup flow from the docs instead of relying on older

examples

Key Setup Areas

• package installation for the app's framework
• convex.json with the authKit section for dev, and preview or prod if

needed

• environment variables such as WORKOS_CLIENT_ID, WORKOS_API_KEY, and

redirect configuration

• convex/auth.config.ts wiring for WorkOS-issued JWTs
• client provider setup and token flow into Convex
• login callback and redirect configuration

Files and Env Vars To Expect

• convex.json
• convex/auth.config.ts
• frontend auth provider wiring
• callback or redirect route setup where the framework requires it
• WorkOS environment variables commonly include:
• WORKOS_CLIENT_ID
• WORKOS_API_KEY
• WORKOS_COOKIE_PASSWORD
• VITE_WORKOS_CLIENT_ID
• VITE_WORKOS_REDIRECT_URI
• NEXT_PUBLIC_WORKOS_REDIRECT_URI

For a managed WorkOS team, convex dev can provision the AuthKit environment and write local env vars such as VITE_WORKOS_CLIENT_ID and VITE_WORKOS_REDIRECT_URI into .env.local for Vite apps.

Concrete Steps

1. Choose Convex-managed or existing WorkOS team 2. Create or update convex.json with the authKit section for the framework in use 3. Make sure the dev redirectUris, appHomepageUrl, corsOrigins, and local redirect env vars match the app's actual local port 4. For a managed WorkOS team, run npx convex dev and follow the interactive onboarding flow 5. For an existing WorkOS team, get WORKOS_CLIENT_ID and WORKOS_API_KEY from the WorkOS dashboard and set them with npx convex env set 6. Create or update convex/auth.config.ts for WorkOS JWT validation 7. Run the normal Convex dev or deploy flow so backend config is synced 8. Wire the WorkOS client provider in the app 9. Configure callback and redirect handling 10. Verify the user can sign in and return to the app 11. Verify Convex sees the authenticated user after login 12. If the user wants production-ready setup, configure the production client ID, API key, redirect URI, and deployment settings too

Gotchas

• The docs split setup between Convex-managed and existing WorkOS teams, so ask

which path the user wants if it is not obvious

• Keep dev and prod WorkOS configuration separate where the docs call for

different client IDs or API keys

• Only add storeUser or a users table if the app needs first-class user rows

inside Convex

• Do not mix dev and prod WorkOS credentials or redirect URIs
• If the repo already contains WorkOS setup, preserve the current tenant model

unless the user wants to change it

• For managed WorkOS setup, convex dev is interactive the first time. In

non-interactive terminals, stop and ask the user to complete the onboarding prompts.

• convex.json is not optional for the managed AuthKit flow. It drives redirect

URI, homepage URL, CORS configuration, and local env var generation.

• If the frontend starts on a different port than the one in convex.json, the

hosted WorkOS sign-in flow will point to the wrong callback URL. Update convex.json, update the local redirect env var, and run npx convex dev again.

• Vite can fall off 5173 if other apps are already running. Do not assume the

default port still matches the generated AuthKit config.

• A successful WorkOS sign-in should redirect back to the local callback route

and then reach a Convex-authenticated state. Do not stop at "the hosted WorkOS page loaded."

Production

• Ask whether the user wants dev-only setup or production-ready setup
• If the answer is production-ready, make sure the production WorkOS client ID,

API key, redirect URI, and Convex deployment config are all covered

• Verify the production redirect and callback settings before calling the task

complete

• Do not silently write a notes file into the repo by default. If the user wants

rollout or handoff docs, create one explicitly.

Validation

• Verify the user can complete the login flow and return to the app
• Verify the callback URL matches the real frontend port in local dev
• Verify Convex receives authenticated requests after login
• Verify convex.json matches the framework and chosen WorkOS setup path
• Verify convex/auth.config.ts matches the chosen WorkOS setup path
• Verify environment variables differ correctly between local and production

where needed

• If production-ready setup was requested, verify the production WorkOS

configuration is also covered

Checklist

• [ ] Confirm the user wants WorkOS AuthKit
• [ ] Ask whether the user wants local-only setup or production-ready setup
• [ ] Choose Convex-managed or existing WorkOS team
• [ ] Create or update convex.json
• [ ] Configure WorkOS environment variables
• [ ] Configure convex/auth.config.ts
• [ ] Verify authenticated requests reach Convex after login
• [ ] If requested, configure the production deployment too