Secret Rotation

Rotation Schedule

Secret	Rotation Frequency	Impact of Rotation
JWT_SECRET	Every 90 days	All active sessions invalidated (or none with dual-secret)
APP_ENCRYPTION_KEY	Annually	Requires data re-encryption migration
MFA_ENCRYPTION_KEY	Annually	Requires re-encryption migration; users locked out if skipped
ENROLLMENT_KEY_PEPPER	Annually	All unexpired enrollment keys invalidated
MFA_RECOVERY_CODE_PEPPER	Annually	All existing MFA recovery codes invalidated
AGENT_ENROLLMENT_SECRET	Every 90 days	Only affects new enrollments
SESSION_SECRET	Every 90 days	All active sessions invalidated
POSTGRES_PASSWORD	Every 90 days	Requires coordinated DB + app restart
REDIS_URL credentials	Every 90 days	Brief reconnection
S3_ACCESS_KEY / S3_SECRET_KEY	Every 90 days	None
CLOUDFLARE_API_TOKEN	Every 90 days	None (existing certs unaffected)
TURN_SECRET	Every 90 days	Active remote sessions may drop
METRICS_SCRAPE_TOKEN	Every 180 days	Brief gap in metrics collection
RESEND_API_KEY / SMTP password	Per provider policy	Brief notification gap
Twilio credentials	Per provider policy	Brief SMS notification gap
ANTHROPIC_API_KEY	Per provider policy	AI assistant unavailable
User API keys	User responsibility	Immediate

Rotating JWT Secret

1. Generate a new secret:

   openssl rand -base64 64

2. Update .env.prod with the new JWT_SECRET

3. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

4. All existing JWTs become invalid — users will need to log in again

Tip

For zero-downtime rotation, implement dual-secret verification: set JWT_SECRET_PREVIOUS to the old value, deploy, wait 7 days for all refresh tokens to expire, then remove JWT_SECRET_PREVIOUS.

Rotating App Encryption Key

Danger

Rotating APP_ENCRYPTION_KEY without re-encrypting existing data will make all previously encrypted values (SSO client secrets, integration tokens) permanently unreadable.

1. Generate a new key:

   openssl rand -hex 32

2. Record the old key securely — you need it for the re-encryption migration

3. Run the re-encryption migration:

   OLD_ENCRYPTION_KEY=<old-key> \
   APP_ENCRYPTION_KEY=<new-key> \
   npx tsx scripts/re-encrypt-secrets.ts

4. Verify decryption of several records with the new key

5. Update APP_ENCRYPTION_KEY in .env.prod to the new key

6. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

Rotating MFA Encryption Key

Danger

Rotating MFA_ENCRYPTION_KEY without re-encryption will lock out all users with MFA enabled. They would need admin intervention to disable and re-enable MFA.

1. Generate a new key:

   openssl rand -hex 32

2. Run a re-encryption migration targeting MFA secret columns (same approach as APP_ENCRYPTION_KEY)

3. Update MFA_ENCRYPTION_KEY in .env.prod

4. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

Rotating Enrollment Key Pepper

Caution

ENROLLMENT_KEY_PEPPER is used for one-way hashing. Rotating it invalidates all unexpired enrollment keys. You must regenerate and redistribute them after rotation.

1. Generate a new pepper:

   openssl rand -hex 32

2. Update ENROLLMENT_KEY_PEPPER in .env.prod

3. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

4. Regenerate enrollment keys and redistribute to anyone deploying new agents

Rotating MFA Recovery Code Pepper

Caution

MFA_RECOVERY_CODE_PEPPER is used for one-way hashing. Rotating it invalidates all existing MFA recovery codes. Users must generate new recovery codes.

1. Generate a new pepper:

   openssl rand -hex 32

2. Update MFA_RECOVERY_CODE_PEPPER in .env.prod

3. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

4. Notify users to regenerate their MFA recovery codes via Settings, or trigger a bulk regeneration as an admin

Rotating Agent Enrollment Secret

1. Generate a new secret:

   openssl rand -hex 32

2. Update .env.prod with the new AGENT_ENROLLMENT_SECRET

3. Restart the API

4. Update any deployment scripts or MDM policies with the new secret

Note

Existing enrolled agents are not affected by enrollment secret rotation. They authenticate using individual bearer tokens, not the enrollment secret. Only new enrollments require the updated secret.

Rotating Session Secret

1. Generate a new secret:

   openssl rand -base64 64

2. Update SESSION_SECRET in .env.prod

3. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

4. All active sessions are invalidated — users must log in again

Rotating Database Password

1. Generate a new password:

   openssl rand -base64 24 | tr -d '/+='

2. Update the password in PostgreSQL:

   docker compose -f docker/docker-compose.prod.yml exec postgres \
     psql -U breeze -c "ALTER USER breeze PASSWORD 'new-password';"

3. Update POSTGRES_PASSWORD and DATABASE_URL in .env.prod

4. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

Tip

For zero-downtime rotation, create a second database user with identical permissions, switch the app to the new user, then drop the old user.

Rotating Redis Credentials

1. Set or update the Redis password:

   redis-cli CONFIG SET requirepass "new-redis-password"
   redis-cli -a "new-redis-password" CONFIG REWRITE

2. Update REDIS_URL in .env.prod:

   REDIS_URL=redis://:new-redis-password@localhost:6379

3. Restart the API and worker processes:

   docker compose -f docker/docker-compose.prod.yml restart api worker

Note

Existing jobs in BullMQ are not lost — they are persisted in Redis and will be processed after reconnection. If using Redis Sentinel or Cluster, update credentials on all nodes first.

Rotating S3 / Object Storage Credentials

1. Create a new access key pair in your S3/R2/MinIO console

2. Update S3_ACCESS_KEY and S3_SECRET_KEY in .env.prod

3. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

4. Verify by uploading and downloading a test file

5. Delete the old access key in your storage provider’s console

Note

Objects already stored in the bucket are unaffected by credential rotation. No data is lost.

Rotating Cloudflare API Token

Note

Only relevant if you have CLOUDFLARE_API_TOKEN and CLOUDFLARE_ZONE_ID configured for mTLS certificate management.

1. In the Cloudflare dashboard, go to My Profile > API Tokens

2. Create a new token with the same permissions (Client Certificates: Edit for the relevant zone)

3. Update CLOUDFLARE_API_TOKEN in .env.prod

4. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

5. Verify by triggering a certificate enrollment or renewal

6. Delete the old token in the Cloudflare dashboard

Note

Existing mTLS certificates already issued to agents remain valid. Only new certificate operations (enrollment, renewal) require a valid API token.

Rotating TURN Secret

1. Generate a new secret:

   openssl rand -hex 32

2. Update TURN_SECRET in both the TURN server configuration and .env.prod

3. Restart the TURN server and the API:

   docker compose -f docker/docker-compose.prod.yml restart api turn

Caution

Active remote desktop and terminal sessions using old TURN credentials will fail when those credentials expire (typically within a few minutes). Users can reconnect.

Rotating Metrics Token

1. Generate a new token:

   openssl rand -hex 32

2. Update METRICS_SCRAPE_TOKEN in .env.prod

3. Update the token file:

   echo "new-token" > monitoring/secrets/metrics_scrape_token
   chmod 600 monitoring/secrets/metrics_scrape_token

4. Restart API and Prometheus:

   docker compose -f docker/docker-compose.prod.yml restart api prometheus

Note

Prometheus will return 401 errors until its config is updated. There will be a brief gap in metrics collection but no data loss.

Rotating Email Provider Credentials

Covers RESEND_API_KEY, SMTP_USER / SMTP_PASS, and MAILGUN_API_KEY.

1. Rotate the credential in the provider’s dashboard (Resend, Mailgun, or your SMTP provider)

2. Update the corresponding env var(s) in .env.prod

3. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

4. Verify by triggering a test notification (e.g., password reset email)

Caution

Keep the old credential active until the new one is deployed. Notifications (password resets, alert emails) will fail between revocation of the old credential and deployment of the new one.

Rotating SMS Provider Credentials (Twilio)

Covers TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN.

1. In the Twilio console, generate a new Auth Token (or create a new API key pair)

2. Update TWILIO_ACCOUNT_SID and/or TWILIO_AUTH_TOKEN in .env.prod

3. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

4. Verify by triggering a test SMS alert

5. Revoke the old credential in the Twilio console

Caution

MFA SMS messages and SMS-based alerts will fail between revocation of the old credential and deployment of the new one. Keep the old credential active until the new one is deployed.

Rotating Anthropic API Key

1. Generate a new API key in the Anthropic console

2. Update ANTHROPIC_API_KEY in .env.prod

3. Restart the API:

   docker compose -f docker/docker-compose.prod.yml restart api

4. Revoke the old key in the Anthropic console

Note

AI assistant queries will fail between revocation of the old key and deployment of the new one. The rest of the platform is unaffected.

User API Keys

User-facing API keys are managed through the application, not through environment variables.

• Individual rotation: Users regenerate their API key via Settings > API Keys > Regenerate, or via POST /api/v1/api-keys
• Admin revocation: Admins can revoke any API key via the admin panel or DELETE /api/v1/api-keys/:id
• Bulk revocation: In a security incident, an admin can revoke all API keys; users must generate new ones

No environment variable changes or restarts are required. The old key is immediately invalidated upon regeneration.

Emergency Rotation

If you suspect any secret has been compromised:

1. Rotate the compromised secret immediately using the procedures above
2. Check audit logs for unauthorized access during the exposure window
3. Rotate related secrets — if JWT_SECRET was compromised, also rotate SESSION_SECRET; if database credentials leaked, also rotate APP_ENCRYPTION_KEY in case encrypted data was exfiltrated
4. Notify affected users if their data may have been accessed
5. File a post-incident report documenting the timeline, impact, and remediation

Danger

Never rotate all secrets simultaneously. Rotate one at a time and verify the system is healthy before moving on. Always test in staging first.