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_AUTH_SECRET environment variable.

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

Warning: Do not change ARCHESTRA_AUTH_SECRET after deployment. Rotating this secret will invalidate all user sessions (forcing re-login), make existing encrypted secrets unreadable, break JWT signing (JWKS private keys are encrypted with this secret), and break two-factor authentication for enrolled users.

See ARCHESTRA_AUTH_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