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

1. Ask whether the user wants local-only setup or production-ready setup now
2. Read the Convex Auth setup guide before writing code
3. 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

1. Install the auth packages:

• npm install @convex-dev/auth @auth/[email protected]

1. Run the initialization command:

• npx @convex-dev/auth

1. Confirm the initializer created:

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

1. Add the required authTables to convex/schema.ts
2. Replace plain ConvexProvider wiring with ConvexAuthProvider
3. Configure at least one auth method in convex/auth.ts
4. Run npx convex dev --once or the normal dev flow to push the updated

schema and generated code

1. Verify the client can sign in successfully
2. Verify Convex receives authenticated identity in backend functions
3. If the user wants production-ready setup, make sure the same auth setup is

configured for the production deployment as well

1. 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/[email protected]
2. Run npx convex dev if the project does not already have a configured

deployment

1. If npx convex dev blocks on interactive setup, ask the user explicitly to

finish configuring the Convex deployment

1. Run npx @convex-dev/auth
2. Confirm the generated auth setup is present before continuing:

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

1. Add authTables to convex/schema.ts
2. Replace ConvexProvider with ConvexAuthProvider in the app entry
3. Configure the selected auth methods in convex/auth.ts
4. Run npx convex dev --once or the normal dev flow so the updated schema and

auth files are pushed

1. Verify login locally
2. 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/[email protected]
• [ ] 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