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: Resend is the default, but you can swap in any email provider (SendGrid, Postmark, Mailgun, etc.) by changing the fetch() call in your email callbacks.

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