Skip to main content

Rotate integration credential keys

This procedure rotates credentials stored on integration connections. It does not rotate HEPHAESTUS_SECURITY_ENCRYPTION_KEY, which protects other application data.

Before you begin​

  • Back up the database and both credential keys.
  • Deploy the key-version-aware release to every runtime before changing key configuration.
  • Generate a new 32-character credential key and store it in the deployment secret store.
  • Choose a positive key version greater than the current version.

Record the starting state on the writer database:

SELECT credentials_key_version, count(*)
FROM connection
WHERE credentials_encrypted IS NOT NULL
GROUP BY credentials_key_version
ORDER BY credentials_key_version;

Stop if the result contains an unexpected version.

Rotate​

  1. Configure every runtime with the existing key as HEPHAESTUS_SECURITY_CREDENTIAL_ENCRYPTION_KEY and its version as HEPHAESTUS_SECURITY_CREDENTIAL_ENCRYPTION_KEY_VERSION. Keep HEPHAESTUS_SECURITY_CREDENTIAL_ROTATION_ENABLED=false. Wait until every instance from the previous release has terminated.
  2. Deploy every runtime with the new key and version as active and the old values as HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY and HEPHAESTUS_SECURITY_PRIOR_CREDENTIAL_ENCRYPTION_KEY_VERSION. Keep rotation disabled.
  3. Run an authenticated provider request for each configured integration kind. Restore the previous configuration if any credential cannot be decrypted.
  4. Set HEPHAESTUS_SECURITY_CREDENTIAL_ROTATION_ENABLED=true on the server runtime only. Disable it if application errors, database latency, replication lag, or WAL growth leave their normal range.
  5. Poll the starting-state query. Rotation is complete only when every row reports the active version.
  6. Disable rotation and repeat the provider checks. Deploy every runtime without the prior key and version.

Failure recovery​

Before rotation starts, restore the previous configuration. After any row is re-encrypted, retain both keys and roll forward. If a batch repeatedly fails, disable rotation and preserve the ciphertext; do not replace an unreadable credential automatically.