> Markdown export: /developers/tenant-envelope-encryption.md
> HTML: /developers/tenant-envelope-encryption
---
description: Operator guidance for TENANT_MASTER_KEY — per-tenant envelope encryption at rest.
audience: operator
---

# 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

::: warning
`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:

```sh
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:

1. Back up the database.
2. Run the re-encryption procedure documented in the eigen repository (see operator scripts under `scripts/`).
3. 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](/developers/troubleshooting) for encrypt/decrypt errors and [Environment variables](/developers/environment-variables) for the full variable list.

## Next steps

- [Overview & quick start](/developers/getting-started) — initial deploy
- [Upgrades & backups](/developers/upgrades-and-backups) — safe key rotation windows