logo uptime kotlinUptime Kotlin
Documentation
Self-hosting / Rotate the master key

Rotate the master key

Replace ENCRYPTION_MASTER_KEY without losing the stored secrets, and what to do if the key is lost.

ENCRYPTION_MASTER_KEY encrypts the stored secrets and the JWT signing key. You can replace it at any time without losing data.

Rotation steps

  1. Generate a new key with openssl rand -base64 32.
  2. On the application and every worker, put the new key in ENCRYPTION_MASTER_KEY and the old one in ENCRYPTION_PREVIOUS_MASTER_KEYS (comma-separated if there are several).
  3. Restart. On startup the application re-encrypts every stored secret with the new key and logs Re-encrypted N stored secret(s). A warning lists the secrets no key could decrypt, to be re-entered.
  4. Remove ENCRYPTION_PREVIOUS_MASTER_KEYS at the next deployment.

If the key is lost

A lost key cannot be recovered. The secrets it encrypted must be re-entered, and the jwt_signing_keys row deleted. Deleting that row signs everyone out.