Production

Ship convex-auth to production: env vars, check/preflight, deployment, and monitoring.

This is the checklist for shipping convex-auth beyond local development.

Pre-deploy checklist

Generate production keys

Use a fresh RS256 keypair for each Convex project. Do not reuse local keys.

pnpm dlx convex env set JWT_PRIVATE_KEY '<private-key-json>'
pnpm dlx convex env set JWKS '<jwks-json>'

Set required environment variables

pnpm dlx convex env set CONVEX_SITE_URL 'https://your-site.convex.site'
pnpm dlx convex env set EMAIL_FROM_ADDRESS 'auth@yourdomain.com'

If you use OAuth, set the provider credentials and register the callback URLs.

Use a real email provider

sendEmail, sendMagicLink, and sendVerificationOTP should call Resend, Postmark, SES, or another provider in production. Returning a console log is fine for local development only.

Run check and preflight

pnpm dlx @vortex-api/convex-auth check
pnpm dlx @vortex-api/convex-auth preflight

check validates imports and exports. preflight verifies environment variables and component mounting.

Deploy

pnpm dlx convex deploy

OAuth callback URLs

GitHub: https://your-site.convex.site/api/auth/callback/github
Google: https://your-site.convex.site/api/auth/callback/google
Discord: https://your-site.convex.site/api/auth/callback/discord

The oauth.trustedOrigins in convex/auth.ts must include the origin you use for callbackURL, errorURL, and newUserURL.

Monitoring

convex-auth exposes runtime observability events you can capture with useAuthRuntimeStatus on the client:

import { useAuthRuntimeStatus } from "@vortex-api/convex-auth/react";

export function AuthStatus() {
  const status = useAuthRuntimeStatus();
  return <pre>{JSON.stringify(status, null, 2)}</pre>;
}

Watch for:

high sign-in failure rates
expired magic links / OTPs
OAuth callback errors
API key rate-limit hits

Key rotation

If you suspect a key leak, rotate immediately:

Generate a new RS256 pair.
Set the new JWKS first so Convex can verify tokens signed with both old and new keys.
Set the new JWT_PRIVATE_KEY.
Invalidate existing sessions if needed by clearing auth_sessions and auth_refresh_tokens for affected users.

What next

Read the Security guide for CAPTCHA, breach detection, rate limits, and 2FA.
Read the Configuration reference for every option.
Run the Testing guide for the conformance consumer and preflight tooling.