convex better auth 2

Convex-native auth runtime with email/password, OAuth, TOTP 2FA, organizations, API keys, and webhooks stored directly in your Convex database.

Installation

npm install convex-auth

Benefits

Run a complete auth stack inside the Convex isolate without an external auth service or long-lived Node.js process
Support email/password, Google, GitHub, and Discord OAuth, TOTP 2FA, backup codes, and trusted devices from a single package
Manage organizations, API keys, webhooks, MCP auth, and agent auth using native Convex tables and actions
Migrate existing Better Auth data to native Convex tables using the included one-time migration bridge

Use cases

how to add authentication to a Convex app without Clerk

convex-auth provides a fully native Convex auth runtime that stores users, sessions, and identities in your own Convex database. You mount the auth component in convex/convex.config.ts, configure providers in convex/auth.ts using convexAuth(), and wrap your React app with ConvexAuthClientProvider. No external auth service is required.

how to implement OAuth login with Google and GitHub in Convex

convex-auth supports Google, GitHub, and Discord OAuth out of the box. After setting GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GOOGLE_CLIENT_ID, and GOOGLE_CLIENT_SECRET as Convex environment variables, you configure them inside the oauth field of convexAuth() in convex/auth.ts. HTTP routes are registered automatically via auth.addHttpRoutes(http) in convex/http.ts.

how to add TOTP two-factor authentication to Convex

convex-auth exposes twoFactorEnable, twoFactorVerifyTOTP, twoFactorVerifyBackupCode, twoFactorDisable, and twoFactorGenerateBackupCodes as named exports from your convex/auth.ts file. These run inside the Convex isolate and store 2FA state in your Convex database alongside the rest of the user record.

how to migrate from Better Auth to native Convex auth

convex-auth includes a one-time Better Auth migration bridge at packages/auth/scripts/migrate-better-auth.ts. You mount both the legacy betterAuth adapter component and the native convexAuth component simultaneously during the cutover, run the migration script to copy data into Convex tables, then remove the Better Auth runtime and adapter packages from your dependencies.

Frequently asked questions

Does convex-auth require an external auth service like Clerk or Auth0?

No. convex-auth is a fully native Convex auth runtime. Users, sessions, identities, organizations, and API keys are stored directly in your Convex database and all auth logic runs inside the Convex isolate. No external auth service or long-lived server process is required.

What authentication methods does convex-auth support?

convex-auth supports email and password authentication with email verification and password reset, OAuth via Google, GitHub, and Discord, TOTP two-factor authentication with backup codes and trusted devices, organizations, API keys, webhooks, MCP OAuth helpers, and agent auth. All of these run inside the Convex native runtime.

How do I set up convex-auth in a new Convex project?

Install the package with npm install convex-auth or pnpm add @vortex-api/convex-auth convex. Generate an RS256 keypair and set JWT_PRIVATE_KEY and JWKS as Convex environment variables. Mount the auth component in convex/convex.config.ts, configure providers in convex/auth.ts using convexAuth(), register HTTP routes in convex/http.ts, then wrap your React app with ConvexAuthClientProvider from @vortex-api/convex-auth/react.

Is convex-auth an official Convex product?

No. convex-auth is an independent, community-driven project built by Vortex and published under the Apache-2.0 license. It is not affiliated with or endorsed by Convex Inc. The package is available on npm as @vortex-api/convex-auth.

How can I verify that my convex-auth installation is configured correctly?

The @vortex-api/convex-auth CLI provides two commands for this. Run pnpm dlx @vortex-api/convex-auth check to validate that your convex/ files are not importing internal package exports. Run pnpm dlx @vortex-api/convex-auth preflight to verify that VITE_CONVEX_URL, CONVEX_SITE_URL, and the component mount are configured correctly against your live deployment.