Encryption Key Management

Every secret in dotEnv Cloud is encrypted with AES-256-GCM before it is stored. What differs between projects is who holds the key. This guide explains the two custody models, how key rotation works, and how to manage key history safely.

Server-managed vs client-managed

Each project uses one of two encryption modes:

Server-managed: dotEnv Cloud generates and stores the encryption key for the project. This is the simplest option: you push and pull without ever handling a key.
Client-managed (zero-knowledge): you hold the key. Encryption and decryption happen entirely on your machine, and dotEnv Cloud only ever sees ciphertext. Even we cannot read your secrets.

Under the hood both modes derive the actual data key with PBKDF2, so the cryptography is identical; the difference is custody of the input key.

Working with a client-managed key

For client-managed projects, the CLI needs your key to encrypt on push and decrypt on pull. You can supply it in several ways, ordered from safest to least safe:

terminal

# Safest: a key file (no warning)

dotenv pull my-app/production/api --client-key=./encryption.key

# The key value directly (warned: leaks via shell history)

dotenv pull my-app/production/api --client-key="$MY_KEY"

# From the environment (warned: leaks via the process environment)

DOTENV_CLIENT_KEY="$MY_KEY" dotenv pull my-app/production/api

If none of these is provided on a client-managed project, the CLI prompts for the key interactively. A --client-key value that looks like a file path but does not exist is treated as an error, not a silent key, to catch typos.

Rotating a server-managed key

Rotate a server-managed key with key rotate. The server generates a fresh random key and re-encrypts the current secrets:

terminal

dotenv key rotate my-app

The --history-policy flag controls what happens to existing backup versions:

keep (default): leaves backups encrypted under the old key, so they remain restorable with it.
re_encrypt: moves backups onto the new key. Use this after a suspected key exposure; afterwards the old key can no longer recover history.

terminal

dotenv key rotate my-app --history-policy=re_encrypt

Rotating client-managed keys

Client-managed key rotation cannot be done from the CLI, because it requires re-encrypting every secret client-side against secret IDs the public API does not expose. Use the rotation flow in the web dashboard instead.

After rotating a client-managed key, older backup versions may still be encrypted under previous keys. Bring them onto the current key (entirely locally) with:

terminal

dotenv key re-encrypt-history my-app --old-key=./old.key

Each old key is verified against its stored proof before use, plaintext never leaves your machine, and the operation is resumable: re-run it to continue where it stopped.

Inspecting key history

List every key version for a project, including which is active and when each was rotated:

terminal

dotenv key history my-app

Switching a project's custody mode does not re-encrypt existing secrets. Plan key handling deliberately, and keep client-managed keys backed up. If you lose a client-managed key, dotEnv Cloud cannot recover the data.

For applying these keys in automation, see Securing CI/CD Pipelines.