Secrets Management

Archestra stores sensitive data like API keys, OAuth tokens, and MCP server credentials as secrets. By default, secrets are encrypted at rest in the database. Optionally, you can configure external secrets storage with HashiCorp Vault.

Note: Existing secrets are not migrated when you enable external storage. Recreate secrets after changing the secrets manager.

Database Storage

Secrets are stored in the database by default. To explicitly configure database storage, set ARCHESTRA_SECRETS_MANAGER to DB.

When secrets are stored in the database, they are automatically encrypted at rest using AES-256-GCM. The encryption key is derived from your ARCHESTRA_SECRETS_ENCRYPTION_SECRET environment variable.

• Encryption and decryption are fully transparent — no configuration is needed beyond setting ARCHESTRA_SECRETS_ENCRYPTION_SECRET.
• Existing plaintext secrets are automatically migrated to encrypted format on startup.

Warning: Rotating ARCHESTRA_SECRETS_ENCRYPTION_SECRET makes existing encrypted secrets unreadable unless they are re-encrypted under the new key. Set ARCHESTRA_SECRETS_ENCRYPTION_SECRET_PREVIOUS to the old value and restart — the app re-encrypts stored secrets under the new key on startup (idempotent).

On every startup, Archestra verifies that the current ARCHESTRA_SECRETS_ENCRYPTION_SECRET still matches the key used to encrypt stored secrets. On a mismatch, startup aborts with an error that names the cause. This catches an accidental rotation — or a database restored from another environment — before it surfaces as scattered decryption failures.

To accept a rotation without re-encrypting, set ARCHESTRA_SECRETS_ACCEPT_NEW_ENCRYPTION_KEY=true for one boot, then unset it; secrets encrypted with the previous key stay unreadable and must be re-entered.

See ARCHESTRA_SECRETS_ENCRYPTION_SECRET for more info.

HashiCorp Vault

Enterprise feature: Contact sales@archestra.ai for licensing information.

In this mode, secret values are stored in Vault instead of the database. Archestra reads, writes, and deletes them in Vault; only references to the secret paths stay in the database.

To enable Vault, set ARCHESTRA_SECRETS_MANAGER to VAULT and configure the address and authentication method.

Required next step: Set the credentials for your chosen auth method — see Vault Authentication.

Note: If ARCHESTRA_SECRETS_MANAGER is set to VAULT but the required environment variables are missing, the system falls back to database storage.

Secret Storage Paths

Vault paths are built as {prefix}/{secretName} — a secret named github_token is written to {prefix}/github_token. ARCHESTRA_HASHICORP_VAULT_SECRET_PATH sets the prefix; its default depends on the configured KV engine version.

For KV v2, list and delete operations use a metadata path derived from ARCHESTRA_HASHICORP_VAULT_SECRET_PATH by swapping /data/ for /metadata/ (e.g., kv/data/platform/archestra → kv/metadata/platform/archestra). Only set ARCHESTRA_HASHICORP_VAULT_SECRET_METADATA_PATH when your metadata prefix doesn't follow this /data/ ↔ /metadata/ convention.

Vault Authentication

Archestra supports three authentication methods for connecting to HashiCorp Vault.

Token Authentication

Kubernetes Authentication

The K8S auth method requires a Vault role configured with a bound service account.

AWS IAM Authentication