Convex Setup Auth
Implement Convex authentication, users-table identity mapping, protected functions, and provider wiring when standing up login for a Convex app.
Overview
Convex Setup Auth is an agent skill for the Build phase that sets up Convex authentication providers, user identity mapping, and protected backend functions.
Install
npx skills add https://github.com/get-convex/agent-skills --skill convex-setup-authWhat is this skill?
- First step: choose auth provider—does not assume Convex Auth, Clerk, WorkOS, Auth0, or custom JWT
- Covers users table, identity mapping, helper functions, and protected Convex functions
- Continues existing repo provider unless the user explicitly switches
- Scoped to Convex implementation—not generic OAuth docs without Convex hooks
Adoption & trust: 62k installs on skills.sh; 31 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need login on Convex but are unsure which provider fits, how to map identities to a users table, and how to guard functions without breaking dev workflows.
Who is it for?
Builders starting Convex auth from scratch or standardizing user tables and protected mutations after picking a provider.
Skip if: Non-Convex stacks, auth that is already fully wired and only needs a tiny bugfix, or OAuth theory without Convex code paths.
When should I use this skill?
Setting up authentication for the first time, implementing user management, creating auth helper functions, or configuring Convex Auth, Clerk, WorkOS, Auth0, or custom JWT.
What do I get? / Deliverables
You get a provider-aligned Convex auth setup with user management helpers and access-controlled functions ready to extend.
- Auth provider configuration aligned to Convex docs
- Users table and identity mapping pattern
- Protected query and mutation examples
Recommended Skills
Journey fit
Auth and access control are core backend build tasks before you can ship protected mutations and user-scoped data. Backend subphase holds server-side identity, roles, and Convex function guards—not one-line patches on finished auth.
How it compares
Convex-focused setup skill—not a generic Next.js auth tutorial or hosted identity product comparison site.
Common Questions / FAQ
Who is convex-setup-auth for?
Solo developers and small teams building SaaS or APIs on Convex who need structured provider setup and server-side access control.
When should I use convex-setup-auth?
During Build backend work when adding first-time login, Clerk or Convex Auth integration, roles on mutations, or a users table mapped to JWT identity.
Is convex-setup-auth safe to install?
Auth skills touch secrets and identity—review the Security Audits panel on this Prism page and never commit API keys; validate provider webhooks in a dev deployment.
SKILL.md
READMESKILL.md - 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](https://docs.convex.dev/auth/convex-auth) - good default when the user wants auth handled directly in Convex - [Clerk](https://docs.convex.dev/auth/clerk) - use when the app already uses Clerk or the user wants Clerk's hosted auth features - [WorkOS AuthKit](https://docs.convex.dev/auth/authkit/) - use when the app already uses WorkOS or the user wants AuthKit specifically - [Auth0](https://docs.convex.dev/auth/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](https://docs.convex.dev/auth/convex-auth), then `references/convex-auth.md` - Clerk: [official docs](https://docs.convex.dev/auth/clerk), then `references/clerk.md` - WorkOS AuthKit: [official docs](https://docs.convex.dev/auth/authkit/), then `references/workos-authkit.md` - Auth0: [official docs](https://docs.convex.dev/auth/auth0), 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](https://docs.convex.dev/auth/functions-auth) for `ctx.auth.getUserIdentity()` - [Storing Users in the Convex Database](https://docs.convex.dev/auth/database-auth) for optional app-level user storage - [Authentication](https://docs.convex.dev/auth) for general auth and authorization guidance - [Convex Auth Authorization](https://labs.convex.dev/auth/authz) 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 Conve