Secret Rotation

Rotation Schedule

Secret	Rotation Frequency	Impact of Rotation
JWT_SECRET	Quarterly	All active sessions invalidated
AGENT_ENROLLMENT_SECRET	After each enrollment batch	Only affects new enrollments
APP_ENCRYPTION_KEY	Annually	Requires data re-encryption migration
MFA_ENCRYPTION_KEY	Annually	Users must re-enroll MFA devices
POSTGRES_PASSWORD	Quarterly	Requires coordinated DB + app restart
METRICS_SCRAPE_TOKEN	Quarterly	Update Prometheus config + API
SESSION_SECRET	Quarterly	All active sessions invalidated

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

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. Only new enrollments require the new secret.

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

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