Breadcrumbs

Vault encryption key

Monopam encrypts stored credentials, secrets, access keys and encrypted settings with a key you provide. Every Monopam process that uses the same database (Web, gateways and their proxies) must have the same key, or credentials cannot be decrypted and connections, reveals and rotations fail.

Applies to

Who can do this

Monopam v2026.10

Platform operators.

Settings

Environment variable

Meaning

Default

MONOPAM_VAULT_KEY

The active key. New data is encrypted with it.

None: a built-in key is used and a warning is logged.

MONOPAM_VAULT_KEY_VERSION

Version number of the active key (1 or higher).

1

MONOPAM_VAULT_KEYS

Older keys kept for decryption, as 1:oldKey;2:otherKey.

None

If the active key is lost, data encrypted with it cannot be recovered. Store the key in your secret store with a backup. The key is read at process start; restart every process after changing it.

Set the key for the first time

  1. Generate a random key, for example openssl rand -base64 48, and store it safely.

  2. Set MONOPAM_VAULT_KEY and MONOPAM_VAULT_KEY_VERSION=1 for the application containers and for every gateway host (on Windows as machine-level environment variables), then restart them.

  3. Check the key status as a super administrator: GET /api/vaultmaintenance/key-status should return "isExternallyKeyed": true and the expected activeKeyVersion.

  4. Open an RDP or SSH session to confirm the gateway can decrypt credentials.

  5. Re-encrypt existing data once per tenant: POST /api/vaultmaintenance/reencrypt, then follow GET /api/vaultmaintenance/reencrypt/<jobId> until it finishes with TotalFailed = 0.

Rotate the key

  1. Generate a new key.

  2. On every target, set MONOPAM_VAULT_KEY to the new key, MONOPAM_VAULT_KEY_VERSION=2 and MONOPAM_VAULT_KEYS=1:<old key>.

  3. Restart all processes and confirm activeKeyVersion is 2.

  4. Run the re-encryption job and confirm TotalFailed = 0.

  5. Remove the old key from MONOPAM_VAULT_KEYS and restart again.

To roll back before re-encryption finishes, keep both keys in the key ring and switch the active version back.

Checklist

  • Key generated and stored in a secret store.

  • Same key and version on the application and every gateway host.

  • All processes restarted.

  • Key status shows the external key and the right version.

  • An RDP or SSH test connection works.

  • Re-encryption finished with no failures in every tenant.

Troubleshooting

What you see

Why

What to do

Vault key version ... is not configured in a gateway log.

That host lacks the key or has a different version.

Give it the same key and version and restart it. No data is lost.

Re-encryption reports failures.

The key was not distributed to all processes, or the wrong key was used.

Check the logs; rows that cannot be decrypted are left untouched.

  • Recovery objectives (RTO and RPO)

  • Manage gateways

  • System settings