Master key custody

WI_MASTER_KEY encrypts every stored provider key. It is generated once, cannot be regenerated, and must be backed up off the box.

For: Administrators responsible for a deployment's secrets · Last updated

WI_MASTER_KEY is the key that encrypts every provider API key your company stores in Workforce Intelligence. Treat it as the most important value on the box.

The rules#

  • It is generated once. On the AWS path the template creates it on first boot. On your own server install.sh creates it, or you generate it yourself with openssl rand -base64 32. Nothing ever regenerates it afterwards. install.sh and the template both leave an existing .env alone.
  • Back it up off the box. Copy /opt/wi/.env (or the .env next to your compose file) to a secret manager or another secure location that is separate from the machine and from the machine's volume backups. Do this as soon as the file exists.
  • Losing it makes stored provider keys unrecoverable. The provider keys are encrypted with AES-GCM and can be decrypted only with the same master key. If the key is lost or changed, the application cannot read them. You would have to enter each provider key again.
  • A restored volume or snapshot is unreadable without the same key. Store the key separately from the volume it protects. A backup of the disk that also holds the only copy of the key does not help you if the disk is lost.
  • The application refuses to start without it. The Compose file requires WI_MASTER_KEY, and the application's boot check stops with "WI_MASTER_KEY is unset" when it is empty. The application also reports "WI_MASTER_KEY incorrect or invalid for this secret" if you change it after keys were stored.

What you should and should not do#

  • Do keep a copy of the whole .env, because WI_SESSION_SECRET lives there too.
  • Do restrict the file to root (mode 0600), which the installer and template do for you.
  • Do not paste the key into tickets, chat, or logs.
  • Do not edit or replace WI_MASTER_KEY on a deployment that already stores provider keys.

Why it is not in the AWS template#

The template generates the key on the instance. The key value never appears in the template, in a stack parameter, in the instance's user data, or in any AWS API call, so nobody who can describe the instance can read it. That also means AWS holds no copy for you: the only copy is the file on the instance's root volume, so your off-box backup of .env is what protects you. See Backups and recovery on AWS.