Environment Variables

Self-hosted deployments only. This page covers the environment variables required when you run your own Convex + Next.js stack. If you use Banata as a managed service, you can skip this page entirely. Hosted app integrations usually only need BANATA_API_KEY and, optionally, BANATA_AUTH_URL if you use a custom Banata auth domain.

Banata Auth reads environment variables from two separate runtimes: the Convex backend (server-side) and the Next.js frontend. Setting each variable in the right place is essential for everything to work correctly.

Quick Reference

Convex Environment Variables

You set these on your Convex deployment with npx convex env set. They're available to your Convex functions via process.env.

Core

# Set core variables
npx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)"
npx convex env set SITE_URL "http://localhost:3000"

Social OAuth Providers

You only need to set credentials for the providers you've enabled in your socialProviders configuration.

For hosted Banata projects, setting environment variables in your own app is not enough to register a provider in the Banata dashboard. The provider must also be saved to the project through the dashboard or saveSocialProviderCredential(...).

# Example: GitHub OAuth
npx convex env set GITHUB_CLIENT_ID "Ov23li..."
npx convex env set GITHUB_CLIENT_SECRET "your-secret"
 
# Example: Google OAuth
npx convex env set GOOGLE_CLIENT_ID "123456.apps.googleusercontent.com"
npx convex env set GOOGLE_CLIENT_SECRET "GOCSPX-..."

Email Provider

npx convex env set RESEND_API_KEY "re_..."

Tip: You can manage Resend, SendGrid, Amazon SES, Mailgun, Postmark, and Cloudflare Email Service from Emails > Providers.

Phone And WhatsApp OTP Providers

Banata Auth exposes phone OTP state and endpoints. Configure delivery from SMS > Providers, or provide your own delivery function through productionReadiness.sendPhoneOtp.

Never log raw OTPs, provider tokens, or full phone numbers in production logs.

Production Inventory Evidence

Use testing/auth-production-env-inventory-template.json when you prepare the managed production launch evidence.

For each required variable, record:

• the runtime that owns the variable
• whether the value is present
• the secret-store or deployment metadata, with the value redacted
• whether the value is scoped to production only
• notes for any missing, blocked, or rotated value

Then run:

bun run verify:auth-env-inventory-template

Do not paste raw API keys, OAuth secrets, OTPs, cookies, session tokens, refresh tokens, KMS plaintext, or provider credentials into the inventory file. The production gate only accepts redacted inventory and log-review evidence.

Passkeys (WebAuthn)

npx convex env set PASSKEY_RP_ID "myapp.com"
npx convex env set PASSKEY_ORIGIN "https://myapp.com"

Managing Convex Variables

# List all variables on your deployment
npx convex env list
 
# Remove a variable
npx convex env unset GITHUB_CLIENT_ID

Next.js Environment Variables (.env.local)

These live in your .env.local file and are available to your Next.js application at build and runtime.

Example .env.local

# Convex deployment
CONVEX_DEPLOYMENT=dev:your-deployment-name
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
 
# App URL
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Local Development

When you run Convex locally with npx convex dev, your .env.local should point to the local endpoints:

CONVEX_DEPLOYMENT=local:local-your-project-name
NEXT_PUBLIC_CONVEX_URL=http://127.0.0.1:3210
NEXT_PUBLIC_CONVEX_SITE_URL=http://127.0.0.1:3211
NEXT_PUBLIC_SITE_URL=http://localhost:3000

NEXT_PUBLIC_ Safety Reminder

Any variable prefixed with NEXT_PUBLIC_ gets embedded in your client-side JavaScript bundle and is visible to every user. Never put secrets in NEXT_PUBLIC_ variables.

Production Checklist

Before you go live, walk through each item:

• BETTER_AUTH_SECRET is a unique, strong random value (different from development)
• SITE_URL points to your production domain (e.g., https://myapp.com)
• NEXT_PUBLIC_CONVEX_URL points to your production Convex deployment
• NEXT_PUBLIC_CONVEX_SITE_URL points to your production Convex site URL
• OAuth callback URLs in each provider's dashboard are updated to production URLs
• PASSKEY_RP_ID is your production domain (not localhost)
• PASSKEY_ORIGIN is your production origin (with https://)
• Email provider API key is set and verified
• No development secrets are reused in production
• .env.local is listed in .gitignore (never commit secrets)

Template .env.local

Copy this into your project as a starting point:

# Convex deployment (filled automatically by `npx convex dev`)
CONVEX_DEPLOYMENT=dev:your-deployment-name
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
 
# App URL
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Then set your Convex-side variables:

npx convex env set BETTER_AUTH_SECRET "$(openssl rand -base64 32)"
npx convex env set SITE_URL "http://localhost:3000"
# Add OAuth and email provider secrets as needed

Next Steps

• Convex Integration — Deep dive into the Convex backend configuration
• Deploy — Ship your self-hosted instance to production
• Quick Start — Set up a new project from scratch
• Auth Configuration — Configure authentication methods and plugins