Auth Setup
Install this skill when implementing Convex authentication, user tables, identity mapping, and provider-specific setup for the first time or migrating providers.
Overview
Auth Setup is an agent skill for the Build phase that configures Convex authentication with provider choice, user management, and access-control patterns.
Install
npx skills add https://github.com/get-convex/agent-skills --skill auth-setupWhat is this skill?
- Provider-aware flow: confirm Convex Auth, Clerk, WorkOS AuthKit, Auth0, or custom JWT before coding
- User management patterns: users table, identity mapping, and access-control helpers
- Matches official Convex auth docs paths so agents do not assume a default host
- Use when creating auth helper functions and securing queries and mutations
- First-time setup and provider switch guidance in one skill
- Supports Convex Auth, Clerk, WorkOS AuthKit, Auth0, and custom JWT paths per Convex docs
Adoption & trust: 514 installs on skills.sh; 31 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are adding login to a Convex app but multiple auth providers and identity rules make it easy to ship insecure or inconsistent server checks.
Who is it for?
Indie builders on Convex who want the agent to ask which auth stack to use and then implement server-side patterns correctly.
Skip if: Non-Convex stacks, or apps where auth is already fully configured and you only need a one-line UI tweak.
When should I use this skill?
Setting up Convex authentication with proper user management, identity mapping, and access control; implementing auth flows.
What do I get? / Deliverables
Convex auth is wired with the chosen provider, user records mapped to identities, and reusable helpers that enforce access on backend functions.
- Auth provider configuration
- Users schema and identity mapping
- Access-control helper functions
Recommended Skills
Journey fit
Auth is foundational backend work done while the product stack is being assembled, before you can safely ship user-facing flows. Backend is the canonical shelf because Convex auth rules, mutations, and identity live in server functions and schema—not in marketing pages.
How it compares
Convex-focused backend skill—not a generic OAuth essay and not an MCP server for identity vendors.
Common Questions / FAQ
Who is auth-setup for?
Solo developers building SaaS or agent backends on Convex who need server-side auth, users tables, and provider integration without re-reading every doc page.
When should I use auth-setup?
During Build backend work when standing up first-time auth, switching providers, or adding identity-aware helpers before shipping protected features.
Is auth-setup safe to install?
Auth touches secrets and identity; review the Security Audits panel on this page and never commit API keys—use Convex and provider dashboards for credentials.
SKILL.md
READMESKILL.md - Auth Setup
# 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) ## 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 Then read `references/common-patterns.md` for the Convex-side patterns that apply across providers: - mapping `ctx.auth.getUserIdentity()` to a `users` table - `getCurrentUser` and `getCurrentUserOrNull` - authorization helpers such as `requireAdmin` - ownership checks and team membership checks - public, private, and hybrid query patterns Do not invent provider-specific setup from memory when the docs are available. Do not assume provider initialization commands finish the entire integration. Verify generated files and complete the post-init wiring steps the provider reference calls out. ## 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. Apply the shared Convex patterns from `references/common-patterns.md` 6. Wire `storeUser` or equivalent identity sync only if the app needs a `users` table 7. Add authorization checks for ownership, admin access, or team access as needed 8. Verify login state, protected queries, environment variables, and production configuration if requested If the flow blocks on interactive provider or deployment setup, ask t