Loading components
Convex Auth
Convex Auth v2 adds transactional, reactive authentication to Convex apps with username/password, passkeys, and OAuth support, type-checked end-to-end.
Installation
npm install @convex-dev/authAbout Convex Auth
Convex Auth provides transactional, reactive authentication built natively on Convex, supporting username/password, email/password with verification and recovery, passkeys, and OAuth providers including Google, Apple, and GitHub. It is type-checked end-to-end and designed to work with AI agents. The library ships as a set of composable Convex components that handle token issuance, session management, and user creation hooks, keeping auth state reactive and consistent with the rest of your Convex data.
Benefits
- Implement username/password, email/password, passkey, and OAuth sign-in without third-party auth services
- Get end-to-end TypeScript type safety across auth functions, user mutations, and client hooks
- Integrate authentication directly into the Convex component system so auth state is reactive and consistent with your database
- Support AI agent workflows with agent-friendly session and token handling built in
Use cases
how to add username and password login to a Convex app
Convex Auth v2 provides a `setupUsernamePassword` function that wires up sign-up, sign-in, and password change mutations on your Convex backend. On the client, `useSignUpWithUsernamePassword` and `useSignInWithUsernamePassword` hooks from `@convex-dev/auth/methods/username-password/react` call those functions directly. You register the core `auth`, `authPassword`, and `authUsername` components in `convex/convex.config.ts` to get started.
how to add OAuth Google GitHub Apple login to Convex
Convex Auth v2 includes built-in OAuth support for Google, Apple, and GitHub. You register the corresponding OAuth component in `convex/convex.config.ts` and use the matching sign-in method from the package. The examples directory contains working end-to-end apps for each provider under `examples/react-google`, `examples/react-apple`, and `examples/react-github`.
how to add passkey authentication to a Convex application
Convex Auth v2 supports passkey-based login through the `usernamePasskey` method, using the core, passkey, and username components. The `examples/react-passkey` and `examples/react-passkey-basic` directories demonstrate minimal working implementations. You register the components in `convex/convex.config.ts` and use the corresponding client hooks to trigger WebAuthn flows.
how to add email verification and password recovery to Convex auth
Convex Auth v2 provides an `emailPassword` method that includes sign-up with email validation, password recovery, and email or password change flows. The `examples/react-email-password` example shows a complete backend and frontend setup. You register the core, password, and email components in `convex/convex.config.ts` and wire up the provided server functions in `convex/auth.ts`.
Frequently asked questions
What sign-in methods does Convex Auth v2 support?
Convex Auth v2 supports username plus password, email plus password with email verification and password recovery, username plus passkey via WebAuthn, and OAuth with Google, Apple, and GitHub. All methods are implemented as Convex components registered in `convex/convex.config.ts` and exposed as typed server functions.
How does Convex Auth v2 differ from Convex Auth v1?
Convex Auth v2 is the currently recommended authentication solution for Convex applications. Convex Auth v1 is no longer recommended but continues to receive security updates and is maintained on the `v1` branch of the GitHub repository. v2 uses the Convex component system and is described as agent friendly, with improved TypeScript type checking end-to-end.
Does Convex Auth v2 require an external auth provider like Auth0 or Clerk?
No. Convex Auth v2 runs entirely within your Convex deployment as a set of Convex components. It does not require a third-party authentication service. OAuth flows for Google, Apple, and GitHub are supported natively without routing through an external identity provider.
How do I create a user record when someone signs up with Convex Auth v2?
Convex Auth v2 lets you attach user lifecycle callbacks via `attachUserCallbacks` on the method setup object. You pass a reference to an internal mutation, such as `internal.users.createUser`, and that mutation receives provider metadata and returns the new user id. This keeps your users table schema fully under your control.
Is Convex Auth v2 compatible with Next.js and server-side rendering?
Yes. The `examples/nextjs` directory in the Convex Auth repository demonstrates a Next.js application with SSR sign-in using Convex Auth v2. The package provides the necessary server-side utilities alongside the React client hooks.
Links
Components
Open-source building blocks for your Convex app
Browse components in this category.