Knowledge > Runbooks > Deployment > Env Var Rotation

Rotate an API Key / Environment Variable

Update a secret API key across all relevant environments after a key compromise, expiration, or planned rotation.

Prerequisites

• vercel CLI logged in (vercel whoami → churchwiseai-5386)
• Access to the external service where the key will be regenerated
• WSL access (if the key is used by the voice agent)

Safety Rule

Rotate one key at a time. Generate the new key → update environments → verify the service works → then revoke the old key. Never revoke the old key before verifying the new one works.

Steps

1. Identify all environments that use the key Check which codebases reference the env var:

   grep -r "VAR_NAME" /c/dev/churchwiseai-web/src /c/dev/pewsearch/web/src /c/dev/sermon-illustrations/src

   Also check:

   • churchwiseai-web/voice-agent-livekit/.env (voice agent env)
   • Vercel project env vars for each project

2. Generate the new key in the external service dashboard (Do not revoke the old key yet.)

3. Update Vercel env vars for each affected project

   echo "new-secret-value" | vercel env add VAR_NAME production --project churchwiseai-web
   echo "new-secret-value" | vercel env add VAR_NAME production --project pewsearch-web
   echo "new-secret-value" | vercel env add VAR_NAME production --project sermon-illustrations

   Only update the projects that actually use the key. Check step 1.

4. Update the voice agent env vars if applicable

   Voice agent env vars are passed as secrets at deploy time via the LiveKit CLI. Update the .env file in voice-agent-livekit/ and redeploy:

   # Edit C:\dev\churchwiseai-web\voice-agent-livekit\.env with the new value, then redeploy:
   C:\dev\lk.exe agent deploy --project cwa-voice --silent

5. Trigger a redeploy to pick up the new env var for each affected web project

   vercel --prod --project churchwiseai-web

   Or push an empty commit to the deploy branch:

   git commit --allow-empty -m "chore: trigger redeploy for key rotation"
   git push

6. Redeploy the voice agent if its key was updated

   Deploy via the LiveKit CLI from the voice-agent-livekit/ directory:

   C:\dev\lk.exe agent deploy --project cwa-voice --silent

7. Verify each affected service still works

   • For churchwiseai-web: visit https://churchwiseai.com and test a chatbot conversation
   • For voice agent: call a configured church number and verify it answers
   • For PewSearch: visit https://pewsearch.com and verify search works
   • For ITW: visit https://illustratetheword.com and verify illustrations load

8. Revoke the old key in the external service dashboard Only do this after verifying all services work with the new key.

9. Update knowledge/.env if the rotated key is stored there (e.g., STRIPE_LIVE_SECRET_KEY)

   # Edit C:\dev\knowledge\.env directly — this file is gitignored

Common Keys and Their Locations

Key	Used By	Vercel Projects
NEXT_PUBLIC_SUPABASE_ANON_KEY	All web apps	churchwiseai-web, pewsearch-web, sermon-illustrations
SUPABASE_SERVICE_ROLE_KEY	All web app APIs	churchwiseai-web, pewsearch-web, sermon-illustrations
STRIPE_SECRET_KEY (test)	Payments	churchwiseai-web, pewsearch-web, sermon-illustrations
STRIPE_LIVE_SECRET_KEY	Payments (live)	churchwiseai-web, pewsearch-web, sermon-illustrations
STRIPE_WEBHOOK_SECRET	Webhooks	churchwiseai-web, pewsearch-web, sermon-illustrations
TWILIO_AUTH_TOKEN	Voice/SMS	churchwiseai-web, voice-agent-livekit/.env
RESEND_API_KEY	Transactional email	churchwiseai-web
MAILERLITE_API_KEY	Marketing email	churchwiseai-web

Verification

After rotation is complete:

vercel env ls --project churchwiseai-web

Confirm the key exists and was recently updated (the timestamp will reflect the update).

See Also

• rollback.md — if rotation caused an outage
• deploy-voice-agent.md — voice agent deploy steps