Tenant envelope encryption
In plain terms: A master secret (
TENANT_MASTER_KEY) encrypts each user's sensitive data at rest — set it once at deploy time and never commit it to git.
Eigen Mesh encrypts sensitive per-tenant data at rest using envelope encryption keyed by TENANT_MASTER_KEY.
Who this is for
- Operators setting up or rotating encryption keys on self-hosted deployments
TENANT_MASTER_KEY is the root of all tenant encryption. Store it only in secrets managers or .env on the server — never in git, tickets, or chat logs. Rotating it without a re-encryption migration will break existing data.
Setup
Generate a strong master key before first deploy:
openssl rand -base64 32
Set TENANT_MASTER_KEY in your .env (eigen repo) or hosting dashboard. Never commit this value to git.
Rotation
Changing TENANT_MASTER_KEY without a re-encryption migration will break decrypt for existing tenant data. Plan rotation as a maintenance window:
- Back up the database.
- Run the re-encryption procedure documented in the eigen repository (see operator scripts under
scripts/). - Deploy with the new key only after re-encryption completes.
Symptoms
| Symptom | Likely cause |
|---|---|
| Encrypt/decrypt errors after deploy | TENANT_MASTER_KEY missing, wrong, or changed without re-encryption |
| New users work, old users fail | Key rotation without migration |
Troubleshooting
See Troubleshooting for encrypt/decrypt errors and Environment variables for the full variable list.
Next steps
- Overview & quick start — initial deploy
- Upgrades & backups — safe key rotation windows