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:4 Sets up Convex authentication with user management, identity mapping, and5 access control. Use this skill when adding login or signup to a Convex app,6 configuring Convex Auth, Clerk, WorkOS AuthKit, Auth0, or custom JWT7 providers, wiring auth.config.ts, protecting queries and mutations with8 ctx.auth.getUserIdentity(), creating a users table with identity mapping, or9 setting up role-based access control, even if the user just says "add auth" or10 "make it require login."11metadata:12 source: https://skillmd.com/skills/get-convex/convex-setup-auth13---1415# Convex Authentication Setup1617Implement secure authentication in Convex with user management and access18control.1920## When to Use2122- Setting up authentication for the first time23- Implementing user management (users table, identity mapping)24- Creating authentication helper functions25- Setting up auth providers (Convex Auth, Clerk, WorkOS AuthKit, Auth0, custom26 JWT)2728## When Not to Use2930- Auth for a non-Convex backend31- Pure OAuth/OIDC documentation without a Convex implementation32- Debugging unrelated bugs that happen to surface near auth code33- The auth provider is already fully configured and the user only needs a34 one-line fix3536## First Step: Choose the Auth Provider3738Convex supports multiple authentication approaches. Do not assume a provider.3940Before writing setup code:41421. Ask the user which auth solution they want, unless the repository already43 makes it obvious442. If the repo already uses a provider, continue with that provider unless the45 user wants to switch463. If the user has not chosen a provider and the repo does not make it obvious,47 ask before proceeding4849Common options:5051- [Convex Auth](https://docs.convex.dev/auth/convex-auth) - good default when52 the user wants auth handled directly in Convex53- [Clerk](https://docs.convex.dev/auth/clerk) - use when the app already uses54 Clerk or the user wants Clerk's hosted auth features55- [WorkOS AuthKit](https://docs.convex.dev/auth/authkit/) - use when the app56 already uses WorkOS or the user wants AuthKit specifically57- [Auth0](https://docs.convex.dev/auth/auth0) - use when the app already uses58 Auth059- Custom JWT provider - use when integrating an existing auth system not covered60 above6162Look for signals in the repo before asking:6364- Dependencies such as `@clerk/*`, `@workos-inc/*`, `@auth0/*`, or Convex Auth65 packages66- Existing files such as `convex/auth.config.ts`, auth middleware, provider67 wrappers, or login components68- Environment variables that clearly point at a provider6970## After Choosing a Provider7172Read the provider's official guide and the matching local reference file:7374- Convex Auth: [official docs](https://docs.convex.dev/auth/convex-auth), then75 `references/convex-auth.md`76- Clerk: [official docs](https://docs.convex.dev/auth/clerk), then77 `references/clerk.md`78- WorkOS AuthKit: [official docs](https://docs.convex.dev/auth/authkit/), then79 `references/workos-authkit.md`80- Auth0: [official docs](https://docs.convex.dev/auth/auth0), then81 `references/auth0.md`8283The local reference files contain the concrete workflow, expected files and env84vars, gotchas, and validation checks.8586Use those sources for:8788- package installation89- client provider wiring90- environment variables91- `convex/auth.config.ts` setup92- login and logout UI patterns93- framework-specific setup for React, Vite, or Next.js9495For shared auth behavior, use the official Convex docs as the source of truth:9697- [Auth in Functions](https://docs.convex.dev/auth/functions-auth) for98 `ctx.auth.getUserIdentity()`99- [Storing Users in the Convex Database](https://docs.convex.dev/auth/database-auth)100 for optional app-level user storage101- [Authentication](https://docs.convex.dev/auth) for general auth and102 authorization guidance103- [Convex Auth Authorization](https://labs.convex.dev/auth/authz) when the104 provider is Convex Auth105106Prefer official docs over recalled steps, because provider CLIs and Convex Auth107internals change between versions. Inventing setup from memory risks outdated108patterns. For third-party providers, only add app-level user storage if the app109actually needs user documents in Convex. Not every app needs a `users` table.110For Convex Auth, follow the Convex Auth docs and built-in auth tables rather111than adding a parallel `users` table plus `storeUser` flow, because Convex Auth112already manages user records internally. After running provider initialization113commands, verify generated files and complete the post-init wiring steps the114provider reference calls out. Initialization commands rarely finish the entire115integration.116117## Core Pattern: Protecting Backend Functions118119The most common auth task is checking identity in Convex functions.120121```ts122// Bad: trusting a client-provided userId123export const getMyProfile = query({124 args: { userId: v.id("users") },125 handler: async (ctx, args) => {126 return await ctx.db.get(args.userId);127 },128});129```130131```ts132// Good: verifying identity server-side133export const getMyProfile = query({134 args: {},135 handler: async (ctx) => {136 const identity = await ctx.auth.getUserIdentity();137 if (!identity) throw new Error("Not authenticated");138139 return await ctx.db140 .query("users")141 .withIndex("by_tokenIdentifier", (q) =>142 q.eq("tokenIdentifier", identity.tokenIdentifier),143 )144 .unique();145 },146});147```148149## Workflow1501511. Determine the provider, either by asking the user or inferring from the repo1522. Ask whether the user wants local-only setup or production-ready setup now1533. Read the matching provider reference file1544. Follow the official provider docs for current setup details1555. Follow the official Convex docs for shared backend auth behavior, user156 storage, and authorization patterns1576. Only add app-level user storage if the docs and app requirements call for it1587. Add authorization checks for ownership, roles, or team access only where the159 app needs them1608. Verify login state, protected queries, environment variables, and production161 configuration if requested162163If the flow blocks on interactive provider or deployment setup, ask the user164explicitly for the exact human step needed, then continue after they complete165it. For UI-facing auth flows, offer to validate the real sign-up or sign-in flow166after setup is done. If the environment has browser automation tools, you can167use them. If it does not, give the user a short manual validation checklist168instead.169170## Reference Files171172### Provider References173174- `references/convex-auth.md`175- `references/clerk.md`176- `references/workos-authkit.md`177- `references/auth0.md`178179## Checklist180181- [ ] Chosen the correct auth provider before writing setup code182- [ ] Read the relevant provider reference file183- [ ] Asked whether the user wants local-only setup or production-ready setup184- [ ] Used the official provider docs for provider-specific wiring185- [ ] Used the official Convex docs for shared auth behavior and authorization186 patterns187- [ ] Only added app-level user storage if the app actually needs it188- [ ] Did not invent a cross-provider `users` table or `storeUser` flow for189 Convex Auth190- [ ] Added authentication checks in protected backend functions191- [ ] Added authorization checks where the app actually needs them192- [ ] Clear error messages ("Not authenticated", "Unauthorized")193- [ ] Client auth provider configured for the chosen provider194- [ ] If requested, production auth setup is covered too