Credential Key Rotation

Use this runbook to rotate CREDENTIAL_ENCRYPTION_KEY without losing stored datasource credential profiles.

For the complete secret lifecycle workflow (setup, bootstrap, non-key rotations, incident response), use:

Scope

Affects encrypted CredentialProfile.secret records in the Postgres datastore (DB_BACKEND=postgres).
Does not rotate JWT signing keys (JWT_SECRET, JWT_GATEWAY_SECRET) or service tokens.

Confirm current services are healthy and you can access admin credential profile views.
Ensure the runtime can connect to the target Postgres datastore (DATABASE_URL or FREEBOARD_POSTGRES_URL).
Ensure both keys are available in a secure secret store.
Keep a recent DB backup/snapshot before running rotation.

Generate a base64-encoded 32-byte key:

bash

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"

Export rotation variables in the shell running the re-encryption:
- DB_BACKEND=postgres
- DATABASE_URL=<target-postgres-url> (or FREEBOARD_POSTGRES_URL=<target-postgres-url>)
- CREDENTIAL_ENCRYPTION_KEY_OLD=<current-key>
- CREDENTIAL_ENCRYPTION_KEY_NEW=<new-key>
Run re-encryption:

bash

npm run credentials:reencrypt

Confirm script output reports completion with expected scanned/updated counts.
Deploy/update runtime secret:
- Set CREDENTIAL_ENCRYPTION_KEY=<new-key>
- Remove CREDENTIAL_ENCRYPTION_KEY_OLD and CREDENTIAL_ENCRYPTION_KEY_NEW from runtime env.
Restart API instances.
Validate:
- Admin credential profile list loads.
- Existing dashboards using credential profiles can still fetch via gateway.

If post-rotation validation fails and you need to revert encrypted records, run the same script with keys swapped:

Then redeploy with the reverted CREDENTIAL_ENCRYPTION_KEY.