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 - 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: