Concepts

The five building blocks of convex-auth for engineers new to Convex.

If you have never built auth in Convex, start here. convex-auth is not an external service. It is a set of Convex components, actions, and React hooks that keep users, sessions, and identities in your Convex database.

The five building blocks

Component

The convexAuth component stores tables for users, identities, sessions, and refresh tokens.

Config

The convexAuth({...}) helper in convex/auth.ts enables providers and exposes actions.

Actions

Convex actions handle sign-up, sign-in, password reset, OAuth callbacks, and 2FA.

HTTP routes

auth.addHttpRoutes(http) mounts email verification, password reset, and OAuth callback routes.

React client

ConvexAuthClientProvider and useAuthActions call the actions from your UI.

Auth state lives in Convex

convex-auth stores everything in your Convex database:

Auth concept	Convex table	Notes
`user`	`users`	One row per person.
`account`	`auth_identities`	Email, OAuth, TOTP, and backup-code data.
`session`	`auth_sessions`	JWT + refresh token sessions.
`refreshToken`	`auth_refresh_tokens`	Long-lived refresh tokens.

Because the data is Convex data, you can query it with ctx.db and write rules/authz against the same tables as the rest of your app. There is no external API to sync.

Sessions are JWTs, not opaque tokens

When a user signs in, convex-auth mints an RS256 JWT. The token contains the user and session id. Convex verifies the token with the JWKS env var on every request. The access token is short-lived; a refresh token in auth_refresh_tokens rotates it without another login.

Set JWT_PRIVATE_KEY and JWKS once.
Send the access token in the Authorization header (React client handles this).
Convex re-hydrates ctx.auth for every query/mutation/action from that token.

Non-deterministic work happens in actions

Convex queries and mutations must be deterministic. Anything that touches a third party, a network, or crypto.subtle lives in a Convex action:

Password hashing (Argon2id / bcrypt) runs in an action.
OAuth code exchange and crypto.randomUUID() run in an action.
Email sending is delegated to your sendEmail callback, which you can call from an action.

This is the same split Convex Auth 2.0 uses: auth data in the DB, auth work in actions.

What is wired where

convex/
- auth.config.ts
  - registers convex-auth as the auth provider
- convex.config.ts
  - mounts the convexAuth component
- auth.ts
  - calls convexAuth({...}) and re-exports actions
- http.ts
  - calls auth.addHttpRoutes(http)
src/
- main.tsx
  - wraps with ConvexAuthClientProvider

Next steps

Install

Set up the packages and keys in Installation.

Configure

Walk through the end-to-end wiring in Quickstart.

Reference

Look up every option in Configuration.