Environment Variables Guide

​

Quick Start

1. Copy .env.example to .env.local
2. Fill in your Supabase credentials
3. Never commit .env.local to version control

​

Required Variables

​

Supabase Configuration

• Description: Your Supabase project URL
• Format: https://{project-ref}.supabase.co
• Example: https://abcdefghijklmnop.supabase.co
• Where to get: Supabase Dashboard → Settings → API → Project URL
• Client Access: ✅ Exposed to client (VITE_ prefix)
• Security: Safe to expose (public URL)

• Description: Supabase anon/public key for client-side access
• Format: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
• Where to get: Supabase Dashboard → Settings → API → anon public key
• Client Access: ✅ Exposed to client (VITE_ prefix)
• Security: Safe to expose (public key, RLS enforced)
• Note: This is the “anon” key, not the service role key

​

Development/Testing Variables

​

Service Role Key (Testing Only)

• Description: Supabase service role key - bypasses RLS
• Format: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
• Where to get: Supabase Dashboard → Settings → API → service_role key
• Client Access: ❌ NEVER use in client code
• Security: ⚠️ CRITICAL - Bypasses all RLS policies
• Usage: Only in test files and edge functions
• Warning: Never commit this value, never use in production client code

​

Optional Variables (Future)

​

Feature Flags

• Description: Enable analytics tracking
• Type: Boolean
• Default: false
• Values: true | false
• Client Access: ✅ Exposed to client

• Description: Enable error tracking (Sentry, LogRocket)
• Type: Boolean
• Default: false
• Values: true | false
• Client Access: ✅ Exposed to client

• Description: Enable AI-powered features
• Type: Boolean
• Default: true
• Values: true | false
• Client Access: ✅ Exposed to client

​

Edge Function Secrets

supabase secrets set RINGCENTRAL_CLIENT_ID=xxxxx
supabase secrets set RINGCENTRAL_CLIENT_SECRET=xxxxx
supabase secrets set RINGCENTRAL_JWT_TOKEN=xxxxx
supabase secrets set OPENROUTER_API_KEY=sk-or-v1-xxxxx

​

Scheduled Tasks / CRON

• Functions: gr-coi-attestation-reminders, hr-credential-expiry-check, and other scheduled functions
• Description: Shared secret used to authenticate cron-triggered edge functions. The function validates Authorization: Bearer <CRON_SECRET> and rejects requests where the header is missing or mismatched.
• Format: Random string (min 32 characters recommended)
• Set via: supabase secrets set CRON_SECRET=<random-string>
• Security: ⚠️ CRITICAL — Must be fail-closed: if CRON_SECRET is not set, the function must throw (not skip auth)

​

Encryption Keys

• Functions: fa-bank-account-encrypt, account verification flows
• Description: AES-256-GCM key for encrypting sensitive bank account data (routing numbers, account numbers) at rest
• Format: Base64-encoded 256-bit key
• Set via: supabase secrets set BANK_ENCRYPTION_KEY=<base64-key>
• Security: ⚠️ CRITICAL — Loss of this key means encrypted bank data is irrecoverable. Rotate via re-encryption migration.

• Functions: hr-ssn-encrypt, payroll processing, tax form generation
• Description: AES-256-GCM key for encrypting Social Security Numbers and Tax Identification Numbers
• Format: Base64-encoded 256-bit key
• Set via: supabase secrets set SSN_ENCRYPTION_KEY=<base64-key>
• Security: ⚠️ CRITICAL — PHI/PII protection. Must never appear in logs or error messages.

​

Portal Authentication

• Functions: portal-auth, portal-verify-token
• Description: HMAC-SHA256 secret for signing and verifying JWTs issued to external portal users (e.g., partner portals, resident portals)
• Format: Random string (min 64 characters recommended)
• Set via: supabase secrets set PORTAL_JWT_SECRET=<random-string>
• Security: ⚠️ Separate from Supabase Auth JWT secret; used only for portal-scoped tokens

• Functions: portal-invite, notification emails containing portal links
• Description: Base URL for the external-facing portal (used to construct invite/reset links)
• Format: https://portal.your-domain.com
• Set via: supabase secrets set PORTAL_BASE_URL=https://portal.your-domain.com

​

Email Service (Entra ID & Gmail)

• ENTRA_CLIENT_SECRET — Client secret for the Entra app registration used for Graph API (e.g. Mail.Send).
• Set via: supabase secrets set ENTRA_CLIENT_SECRET=xxxxx
• Per-org: Configure in Settings → Integrations → Microsoft Entra ID (tenant, app, sender email).

• GMAIL_SERVICE_ACCOUNT_JSON — Full JSON key for the Google Cloud service account (with domain-wide delegation for Gmail API).
• Set via: supabase secrets set GMAIL_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'
• Per-org: Set sender email in Settings → Integrations → Google Workspace (Gmail).

​

SMS Service (RingCentral)

• Function: sms-send, ringcentral-setup
• Where to get: RingCentral Developer Console → your app → Credentials
• Format: xxxxx
• Set via: supabase secrets set RINGCENTRAL_CLIENT_ID=xxxxx

• Function: sms-send, ringcentral-setup
• Where to get: RingCentral Developer Console → your app → Credentials
• Format: xxxxx
• Set via: supabase secrets set RINGCENTRAL_CLIENT_SECRET=xxxxx

• Function: sms-send, ringcentral-setup
• Where to get: RingCentral Developer Console → Credentials → JWT
• Format: JWT string
• Set via: supabase secrets set RINGCENTRAL_JWT_TOKEN=xxxxx

​

AI Service (OpenRouter) - PF-59

• Functions: ai-assistant, ai-document-analyze, generate-report-narrative
• Where to get: OpenRouter Dashboard
• Format: sk-or-v1-xxxxx
• Set via: supabase secrets set OPENROUTER_API_KEY=sk-or-v1-xxxxx
• Note: Replaced LOVABLE_API_KEY as of PF-59 migration

• Functions: All AI-related edge functions
• Description: Application URL for OpenRouter attribution (HTTP-Referer header)
• Format: https://your-app.lovable.app
• Set via: supabase secrets set APP_URL=https://data-mover-pal.lovable.app

​

Model Selection by Module

​

Environment-Specific Configuration

​

Development

VITE_SUPABASE_URL=https://dev-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=dev-anon-key
SUPABASE_SERVICE_ROLE_KEY=dev-service-key  # Testing only

​

Staging

VITE_SUPABASE_URL=https://staging-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=staging-anon-key
# No service role key in staging client

​

Production

VITE_SUPABASE_URL=https://prod-project.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=prod-anon-key
# No service role key in production client

​

Security Best Practices

​

1. Never Commit Secrets

• Use .env.local for local development
• Add .env.local to .gitignore
• Use .env.example as template (no real values)

• Commit .env.local with real values
• Put secrets in .env.example
• Hardcode secrets in code
• Share secrets in chat/email

​

2. VITE_ Prefix Rules

• ✅ Safe: Public URLs, anon keys, feature flags
• ❌ Never: Service role keys, API secrets, passwords

# ✅ SAFE - Public URL
VITE_SUPABASE_URL=https://project.supabase.co

# ❌ DANGEROUS - Secret exposed to client
VITE_SUPABASE_SERVICE_ROLE_KEY=xxxxx  # WRONG!

​

3. Edge Function Secrets

• Set via supabase secrets set KEY=value
• Never in .env.local or client code
• Only accessible in edge function runtime

​

4. Service Role Key

• ⚠️ Bypasses all RLS policies
• ❌ Never use in client code
• ✅ Only in test files and edge functions
• ✅ Only in development/staging

​

Variable Validation

​

Required Variables Check

// src/integrations/supabase/client.ts
const SUPABASE_URL = import.meta.env.VITE_SUPABASE_URL;
const SUPABASE_PUBLISHABLE_KEY = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY;

if (!SUPABASE_URL || !SUPABASE_PUBLISHABLE_KEY) {
  throw new Error('Missing required Supabase environment variables');
}

​

Development Warnings

• Required variables are missing
• Service role key is used in client code (development only)
• Invalid Supabase URL format

​

How to Obtain Keys

​

Supabase Keys

1. Go to Supabase Dashboard
2. Select your project
3. Navigate to Settings → API
4. Copy:
   • Project URL → VITE_SUPABASE_URL
   • anon public key → VITE_SUPABASE_PUBLISHABLE_KEY
   • service_role key → SUPABASE_SERVICE_ROLE_KEY (testing only)

​

Email Provider Secrets

• Entra: ENTRA_CLIENT_SECRET
• Gmail: GMAIL_SERVICE_ACCOUNT_JSON

​

RingCentral Credentials

1. Go to the RingCentral Developer Console
2. Open your app → Credentials
3. Copy:
   • Client ID → RINGCENTRAL_CLIENT_ID
   • Client Secret → RINGCENTRAL_CLIENT_SECRET
   • JWT credential → RINGCENTRAL_JWT_TOKEN
4. Set via Supabase CLI:
   supabase secrets set RINGCENTRAL_CLIENT_ID=xxxxx
   supabase secrets set RINGCENTRAL_CLIENT_SECRET=xxxxx
   supabase secrets set RINGCENTRAL_JWT_TOKEN=xxxxx
   

​

Troubleshooting

​

Issue: “Missing required Supabase environment variables”

1. Check .env.local exists
2. Verify variables are set:
   echo $VITE_SUPABASE_URL
   echo $VITE_SUPABASE_PUBLISHABLE_KEY
   
3. Restart development server
4. Check for typos in variable names

​

Issue: “Invalid Supabase URL”

1. Verify URL format: https://{project-ref}.supabase.co
2. Check for trailing slashes (remove if present)
3. Ensure HTTPS (not HTTP)

​

Issue: “Service role key in client code”

1. Remove SUPABASE_SERVICE_ROLE_KEY from .env.local
2. Only use in test files: tests/**/*.ts
3. Never import in client code: src/**/*.tsx

​

Issue: “Edge function can’t access secrets”

1. Verify secrets are set:
   supabase secrets list
   
2. Redeploy function after setting secrets:
   supabase functions deploy {function-name}
   
3. Check secret names match exactly (case-sensitive)

​

Issue: “CORS errors in development”

1. Verify VITE_SUPABASE_URL points to correct project
2. Check Supabase project CORS settings
3. Ensure edge functions include CORS headers

​

Production Deployment

​

Vercel Environment Variables

• Public client config values are defined at build time in vite.config.ts.
• vercel.json must not contain env or build.env keys.
• CI enforces this via npm run check:no-vercel-env-config.

​

Supabase Edge Function Secrets

1. Set secrets via Supabase CLI (e.g. RingCentral, Entra, Gmail):
   supabase secrets set RINGCENTRAL_CLIENT_ID=xxxxx --project-ref {project-ref}
   supabase secrets set ENTRA_CLIENT_SECRET=xxxxx --project-ref {project-ref}
   
2. Or via Supabase Dashboard → Project Settings → Edge Functions → Secrets

​

Related Documentation

• Edge Functions: docs/integrations/EDGE_FUNCTIONS.md
• Supabase Setup: docs/integrations/SUPABASE_SETUP.md
• Secrets Management: docs/security/SECRETS_MANAGEMENT.md
• .env.example: .env.example (template file)

​

Related Documentation

​

Setup & Configuration

• PWA Setup - PWA configuration and environment requirements
• Setup Quick Start - First-time developer setup including environment variables

​

Development Guides

• Development Quick Reference - Common development tasks