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:
- Ask the user which auth solution they want, unless the repository already
makes it obvious
- If the repo already uses a provider, continue with that provider unless the
user wants to switch
- 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:
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:
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
- Determine the provider, either by asking the user or inferring from the repo
- Ask whether the user wants local-only setup or production-ready setup now
- Read the matching provider reference file
- Follow the official provider docs for current setup details
- Follow the official Convex docs for shared backend auth behavior, user
storage, and authorization patterns
- Only add app-level user storage if the docs and app requirements call for it
- Add authorization checks for ownership, roles, or team access only where the
app needs them
- 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
1---2name: convex-setup-auth3description: Sets up Convex auth, identity mapping, and access control. Use for login, auth4 providers, users tables, protected functions, or roles in a Convex app.5metadata:6 source: https://skillmd.com/skills/openclaw/convex-setup-auth7---89# Convex Authentication Setup1011Implement secure authentication in Convex with user management and access12control.1314## When to Use1516- Setting up authentication for the first time17- Implementing user management (users table, identity mapping)18- Creating authentication helper functions19- Setting up auth providers (Convex Auth, Clerk, WorkOS AuthKit, Auth0, custom20 JWT)2122## When Not to Use2324- Auth for a non-Convex backend25- Pure OAuth/OIDC documentation without a Convex implementation26- Debugging unrelated bugs that happen to surface near auth code27- The auth provider is already fully configured and the user only needs a28 one-line fix2930## First Step: Choose the Auth Provider3132Convex supports multiple authentication approaches. Do not assume a provider.3334Before writing setup code:35361. Ask the user which auth solution they want, unless the repository already37 makes it obvious382. If the repo already uses a provider, continue with that provider unless the39 user wants to switch403. If the user has not chosen a provider and the repo does not make it obvious,41 ask before proceeding4243Common options:4445- [Convex Auth](https://docs.convex.dev/auth/convex-auth) - good default when46 the user wants auth handled directly in Convex47- [Clerk](https://docs.convex.dev/auth/clerk) - use when the app already uses48 Clerk or the user wants Clerk's hosted auth features49- [WorkOS AuthKit](https://docs.convex.dev/auth/authkit/) - use when the app50 already uses WorkOS or the user wants AuthKit specifically51- [Auth0](https://docs.convex.dev/auth/auth0) - use when the app already uses52 Auth053- Custom JWT provider - use when integrating an existing auth system not covered54 above5556Look for signals in the repo before asking:5758- Dependencies such as `@clerk/*`, `@workos-inc/*`, `@auth0/*`, or Convex Auth59 packages60- Existing files such as `convex/auth.config.ts`, auth middleware, provider61 wrappers, or login components62- Environment variables that clearly point at a provider6364## After Choosing a Provider6566Read the provider's official guide and the matching local reference file:6768- Convex Auth: [official docs](https://docs.convex.dev/auth/convex-auth), then69 `references/convex-auth.md`70- Clerk: [official docs](https://docs.convex.dev/auth/clerk), then71 `references/clerk.md`72- WorkOS AuthKit: [official docs](https://docs.convex.dev/auth/authkit/), then73 `references/workos-authkit.md`74- Auth0: [official docs](https://docs.convex.dev/auth/auth0), then75 `references/auth0.md`7677The local reference files contain the concrete workflow, expected files and env78vars, gotchas, and validation checks.7980Use those sources for:8182- package installation83- client provider wiring84- environment variables85- `convex/auth.config.ts` setup86- login and logout UI patterns87- framework-specific setup for React, Vite, or Next.js8889For shared auth behavior, use the official Convex docs as the source of truth:9091- [Auth in Functions](https://docs.convex.dev/auth/functions-auth) for92 `ctx.auth.getUserIdentity()`93- [Storing Users in the Convex Database](https://docs.convex.dev/auth/database-auth)94 for optional app-level user storage95- [Authentication](https://docs.convex.dev/auth) for general auth and96 authorization guidance97- [Convex Auth Authorization](https://labs.convex.dev/auth/authz) when the98 provider is Convex Auth99100Prefer official docs over recalled steps, because provider CLIs and Convex Auth101internals change between versions. Inventing setup from memory risks outdated102patterns. For third-party providers, only add app-level user storage if the app103actually needs user documents in Convex. Not every app needs a `users` table.104For Convex Auth, follow the Convex Auth docs and built-in auth tables rather105than adding a parallel `users` table plus `storeUser` flow, because Convex Auth106already manages user records internally. After running provider initialization107commands, verify generated files and complete the post-init wiring steps the108provider reference calls out. Initialization commands rarely finish the entire109integration.110111## Core Pattern: Protecting Backend Functions112113The most common auth task is checking identity in Convex functions.114115```ts116// Bad: trusting a client-provided userId117export const getMyProfile = query({118 args: { userId: v.id("users") },119 handler: async (ctx, args) => {120 return await ctx.db.get(args.userId);121 },122});123```124125```ts126// Good: verifying identity server-side127export const getMyProfile = query({128 args: {},129 handler: async (ctx) => {130 const identity = await ctx.auth.getUserIdentity();131 if (!identity) throw new Error("Not authenticated");132133 return await ctx.db134 .query("users")135 .withIndex("by_tokenIdentifier", (q) => q.eq("tokenIdentifier", identity.tokenIdentifier))136 .unique();137 },138});139```140141## Workflow1421431. Determine the provider, either by asking the user or inferring from the repo1442. Ask whether the user wants local-only setup or production-ready setup now1453. Read the matching provider reference file1464. Follow the official provider docs for current setup details1475. Follow the official Convex docs for shared backend auth behavior, user148 storage, and authorization patterns1496. Only add app-level user storage if the docs and app requirements call for it1507. Add authorization checks for ownership, roles, or team access only where the151 app needs them1528. Verify login state, protected queries, environment variables, and production153 configuration if requested154155If the flow blocks on interactive provider or deployment setup, ask the user156explicitly for the exact human step needed, then continue after they complete157it. For UI-facing auth flows, offer to validate the real sign-up or sign-in flow158after setup is done. If the environment has browser automation tools, you can159use them. If it does not, give the user a short manual validation checklist160instead.161162## Reference Files163164### Provider References165166- `references/convex-auth.md`167- `references/clerk.md`168- `references/workos-authkit.md`169- `references/auth0.md`170171## Checklist172173- [ ] Chosen the correct auth provider before writing setup code174- [ ] Read the relevant provider reference file175- [ ] Asked whether the user wants local-only setup or production-ready setup176- [ ] Used the official provider docs for provider-specific wiring177- [ ] Used the official Convex docs for shared auth behavior and authorization178 patterns179- [ ] Only added app-level user storage if the app actually needs it180- [ ] Did not invent a cross-provider `users` table or `storeUser` flow for181 Convex Auth182- [ ] Added authentication checks in protected backend functions183- [ ] Added authorization checks where the app actually needs them184- [ ] Clear error messages ("Not authenticated", "Unauthorized")185- [ ] Client auth provider configured for the chosen provider186- [ ] If requested, production auth setup is covered too