Installation

Install convex-auth, generate keys, and set your environment variables.

This guide installs the packages and sets the minimum environment variables. For the full end-to-end wiring, follow Quickstart.

What you need

A Convex project. If you do not have one, run pnpm dlx convex@latest.
pnpm and Node >=22.0.0.
An email service for production (Resend, Postmark, SES, etc.). For local development you can log email drafts.

Steps

Install packages

pnpm add @vortex-api/convex-auth @vortex-api/convex-auth/react convex

Generate signing keys

convex-auth signs session JWTs with RS256. Run this once:

node --input-type=module -e '
import { randomUUID } from "node:crypto";
import { generateKeyPair, exportJWK } from "jose";
const { publicKey, privateKey } = await generateKeyPair("RS256", { extractable: true });
const pub = await exportJWK(publicKey);
const priv = await exportJWK(privateKey);
const kid = randomUUID();
pub.kid = kid;
priv.kid = kid;
console.log("JWT_PRIVATE_KEY=" + JSON.stringify(priv));
console.log("JWKS=" + JSON.stringify({ keys: [pub] }));
'

Set environment variables

pnpm dlx convex env set JWT_PRIVATE_KEY '<private-key-json>'
pnpm dlx convex env set JWKS '<jwks-json>'
pnpm dlx convex env set CONVEX_SITE_URL 'https://your-site.convex.site'
pnpm dlx convex env set EMAIL_FROM_ADDRESS 'auth@yourdomain.com'

Continue to Quickstart

The next page wires the component, convex/auth.ts, and the React client.

Supported versions

convex-auth is tested against the following ranges:

Package / subpath	Version	Convex	React	React Native / Expo	Node	pnpm
`@vortex-api/convex-auth`	`3.x`	`>=1.45.0`	`>=19.0.0`	—	`>=22.0.0`	`10.25.0`
`@vortex-api/convex-auth/react`	`3.x`	`>=1.45.0`	`>=19.0.0`	—	`>=22.0.0`	`10.25.0`
`@vortex-api/convex-auth/react-native`	`3.x`	`>=1.45.0`	`>=19.0.0`	`expo-*` (optional)	`>=22.0.0`	`10.25.0`

Convex — >=1.45.0 covers the modern backend system and generated component API.
React — React 19 is the primary target; the client side does not depend on a specific React 18 release.
Node — CI runs on Node 22 (floor) and Node 24 (newest LTS). Node 20 is EOL; older versions are unsupported.
pnpm — the workspace uses pnpm only.

Updating Convex

If you want to widen the convex peer range:

Update the range in packages/auth/package.json.
Run pnpm run typecheck, pnpm run build, and pnpm test from the repo root.
Do not widen a peer range without running the full test suite.

Optional: set OAuth credentials

If you want Google, GitHub, or Discord sign-in, also set these and register the callback URL https://<CONVEX_SITE_URL>/api/auth/callback/<provider>:

pnpm dlx convex env set GITHUB_CLIENT_ID '...'
pnpm dlx convex env set GITHUB_CLIENT_SECRET '...'
pnpm dlx convex env set GOOGLE_CLIENT_ID '...'
pnpm dlx convex env set GOOGLE_CLIENT_SECRET '...'
pnpm dlx convex env set DISCORD_CLIENT_ID '...'
pnpm dlx convex env set DISCORD_CLIENT_SECRET '...'