--- name: bijection-convex-better-auth-2 description: "Evaluate and integrate the convex better auth 2 component with Bijection." --- # convex better auth 2 Convex-native authentication server and React UI with OAuth, password, TOTP, organizations, API keys, and webhooks. This is an upstream package. It has not been adapted or qualified for Bijection. - Package: convex-better-auth-2.0 - Source: https://github.com/shlomokabareti/convex-better-auth-2.0 - npm: https://www.npmjs.com/package/convex-auth - Directory: https://bijection.com/components/convex-better-auth-2 Read the upstream README for setup, license, and compatibility before using it. ## Integration workflow 1. Read the source README and package manifest at the recorded revision. 2. Confirm the required SDK, dependency availability, and runtime compatibility. 3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name. 4. Keep credentials in the project's existing secret store. 5. Follow the project's execution rules for verification and report what was actually checked. ## Original upstream skill The following guidance describes convex-better-auth-2.0. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately. > Agents: read this skill fully before writing code that uses convex-auth. Follow the installation and configuration steps exactly. # convex-auth ## Instructions Use convex-auth to convex-native auth runtime with email/password, oauth, totp 2fa, organizations, api keys, and webhooks stored directly in your convex database. This Convex component integrates directly with your backend. ### Installation ```bash npm install convex-auth ``` Current npm version: `convex-auth@2.0.3` ### Capabilities - 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 ## Examples ### 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. ## When NOT to use - When a simpler built-in solution exists for your specific use case - If you are not using Convex as your backend - When the functionality provided by convex-auth is not needed ## Troubleshooting **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. ## Resources - [npm package](https://www.npmjs.com/package/convex-auth) - [GitHub repository](https://github.com/shlomokabareti/convex-better-auth-2.0) - [Live demo](https://perfect-dragon-698.convex.site) - [Convex Components Directory](https://www.convex.dev/components/convex-auth) - [Convex documentation](https://docs.convex.dev)