Rotate the master key · Workforce Intelligence docs

Rotate WI_MASTER_KEY when your policy requires it or the key may have been exposed. Rotation re-encrypts only your company's data key, so no credential is re-entered and nothing stored is lost. The application does the work when it starts.

Before you start#

Back up /opt/wi/.env off the box, and take a snapshot of the machine's volume.
You need to edit .env and run Docker Compose on the host, and the admin ability to confirm the result in the product.
Generate the new key:
```
openssl rand -base64 32
```

Rotate#

Edit .env (it is root-only, so use sudo). Add a line with the current WI_MASTER_KEY value as WI_MASTER_KEY_OLD, then replace the WI_MASTER_KEY value with the new key:
```
WI_MASTER_KEY_OLD=<the previous WI_MASTER_KEY value>
WI_MASTER_KEY=<the new key>
```
Re-running install.sh leaves both lines alone.
Apply it. docker compose restart does not re-read .env, so recreate the containers from the deployment directory:
```
cd /opt/wi
sudo docker compose -f docker-compose.prod.yml up -d
```
Sign in as an administrator. Select Settings, then the Administration tab, select Manage on the Secrets card, and find the Encryption keys card below the tabs. Wait for it to say "All credentials use the current master key. Safe to remove WI_MASTER_KEY_OLD."
Delete the WI_MASTER_KEY_OLD line from .env and run the same up -d command again. The card then says "All stored credentials are protected by WI_MASTER_KEY."
Back up the new .env off the box. Keep the previous key too, for as long as any backup that predates the rotation might be restored (see below).

What the Encryption keys card tells you#

Message	Meaning and next step
"WI_MASTER_KEY_OLD is set and still needed — N stored credentials are still encrypted under the previous key."	Keep `WI_MASTER_KEY_OLD` set and run the `up -d` command again to move them to the current key.
"WI_MASTER_KEY_OLD is set and still needed — a data key is still wrapped under the previous key."	Keep `WI_MASTER_KEY_OLD` set and run the `up -d` command again to finish the rotation.
"WI_MASTER_KEY_OLD is set. The only credentials not on the current key can't be opened with either key."	Re-enter the credentials listed on the card, then remove `WI_MASTER_KEY_OLD`.
"All credentials use the current master key. Safe to remove WI_MASTER_KEY_OLD."	Remove `WI_MASTER_KEY_OLD` from `.env` and run the `up -d` command.
"The configured master keys can't unlock the stored credentials."	Set `WI_MASTER_KEY` to the key whose fingerprint the card names (during a rotation, set the previous key as `WI_MASTER_KEY_OLD`) and run the `up -d` command.

The card also shows the fingerprint of WI_MASTER_KEY and, while it is set, of WI_MASTER_KEY_OLD. Compare fingerprints to confirm which key is which. A fingerprint identifies a key and cannot be used to recover it.

If the application will not start#

Production refuses to start when WI_MASTER_KEY and WI_MASTER_KEY_OLD do not match the key stored in the database, when either is not a valid base64 AES key, when WI_MASTER_KEY_OLD is set without WI_MASTER_KEY, or when both hold the same key. The error names the fingerprint stored in the database and the fingerprints of the keys you configured. Fix .env and run the up -d command again. See Production boot checks.

Restoring a backup after a rotation#

A database backup can be read only with the master key that matches the fingerprint stored in it. If the backup was taken before a rotation, set WI_MASTER_KEY to the current key and WI_MASTER_KEY_OLD to the key that was in use when the backup was taken, then confirm on the Encryption keys card as above. A whole-disk restore on AWS brings back the matching .env and needs no extra step. See Backups and recovery on AWS.

Rolling back the application version#

Stored credentials are kept in a format that earlier releases cannot read. If you may need to return to an earlier release, keep a database backup taken before you rotate or upgrade, and restore it rather than only changing the image.