Configuration Reference¶

Complete reference for all AuthVital environment variables and settings.

Environment Variables¶

Core Configuration¶

Or use individual DB_ variables for Cloud SQL.

Security¶

Generate a secure master secret:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Output: a1b2c3d4e5f6...

⚠️ Warning: Changing MASTER_SECRET invalidates all existing tokens and sessions — the stored JWT signing keys can no longer be decrypted.

Database (Cloud SQL)¶

When using Google Cloud SQL, configure individual components instead of DATABASE_URL:

The application constructs DATABASE_URL from these at startup.

CORS¶

Examples:

# Single origin
CORS_ORIGINS=https://app.example.com

# Multiple origins
CORS_ORIGINS=https://app.example.com,https://admin.example.com

# Wildcard subdomain
CORS_ORIGINS=https://*.example.com

# Development (allow localhost)
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

Email (SendGrid)¶

If not configured, emails are logged to console (useful for development).

Bootstrap¶

When SUPER_ADMIN_EMAIL is set and no super admin exists: 1. Creates a super admin account 2. Sends password reset email (or logs to console if email not configured)

Docker Architecture¶

Migrations and the API run as separate services in Docker Compose:

postgres (healthcheck) → migrate (runs once, exits) → api (starts)

The migrate service runs Prisma migrations and bootstrap checks (super admin creation, system roles), then exits. The api service only starts after migrations complete successfully. No RUN_MODE variable is needed.

For CI/CD (e.g., Cloud Run), run the migration image as a one-shot Job before deploying the API service.

Application Settings (Instance)¶

These are configured in the admin panel or via API, stored in the database:

Sign-up Configuration¶

Single-Tenant Mode¶

When enabled: - All signups auto-join the default tenant - No tenant picker is shown - Tokens are always tenant-scoped

Branding (Instance Default)¶

Security Settings¶

Application Configuration¶

Each OAuth application has its own settings:

OAuth Settings¶

Redirect URI Patterns¶

AuthVital supports flexible redirect URI matching:

# Exact match
https://app.example.com/callback

# Wildcard subdomain
https://*.example.com/callback

# Tenant placeholder (validates tenant exists in DB)
https://{tenant}.example.com/callback

# Localhost for development
http://localhost:3000/callback
http://localhost:*/callback

Licensing Settings¶

Access Control¶

Access modes:

Application Branding¶

Each app can override instance branding:

Webhook Settings¶

Tenant Configuration¶

MFA Policies¶

MFA policies:

SSO Configuration¶

Example Configurations¶

Development¶

# .env
DATABASE_URL=postgresql://authvital:localdev123@localhost:5432/authvital
BASE_URL=http://localhost:8000
PORT=8000
NODE_ENV=development
MASTER_SECRET=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
COOKIE_SECURE=false
SUPER_ADMIN_EMAIL=admin@localhost

Production (Cloud Run)¶

# Set via Secret Manager / Cloud Run env vars
DB_HOST=/cloudsql/project:region:instance
DB_USERNAME=postgres
DB_PASSWORD=<from-secret-manager>
DB_DATABASE=authvital
BASE_URL=https://auth.yourcompany.com
NODE_ENV=production
MASTER_SECRET=<from-secret-manager>
COOKIE_SECURE=true
CORS_ORIGINS=https://app.yourcompany.com,https://admin.yourcompany.com
SENDGRID_API_KEY=<from-secret-manager>
SENDGRID_FROM_EMAIL=noreply@yourcompany.com

Production (Self-hosted)¶

# .env
DATABASE_URL=postgresql://authvital:securepassword@db:5432/authvital
BASE_URL=https://auth.yourcompany.com
PORT=8000
NODE_ENV=production
MASTER_SECRET=<generate-secure-key>
COOKIE_SECURE=true
CORS_ORIGINS=https://app.yourcompany.com
SENDGRID_API_KEY=SG.xxxx
SENDGRID_FROM_EMAIL=noreply@yourcompany.com
SENDGRID_FROM_NAME=YourCompany
SUPER_ADMIN_EMAIL=admin@yourcompany.com

Related Documentation¶

• Installation & Deployment
• Architecture Overview
• Security Best Practices