Secret Storage

Archestra encrypts saved credentials in PostgreSQL by default. Use HashiCorp Vault to keep their values outside the database. This storage protects credentials; content encryption protects messages and tool results separately.

With Vault active, Settings → Secrets shows its connection status. The Credentials page shows whether a value is connected, without revealing it.

Database Storage

Database storage is the default. To configure it explicitly, set ARCHESTRA_SECRETS_MANAGER to DB.

Stored secrets are automatically encrypted at rest using AES-256-GCM derived from ARCHESTRA_SECRETS_ENCRYPTION_SECRET.

Key Rotation

Rotate during a maintenance window. All web pods, workers, and other processes using the database secret store must stop before any process starts with the new key. The previous key is used by the startup migration, not by ordinary secret reads; a rolling restart would mix incompatible readers and writers.

1. Back up PostgreSQL and preserve the current key.
2. Stop all application processes that read or write stored secrets.
3. Set ARCHESTRA_SECRETS_ENCRYPTION_SECRET to the new key and ARCHESTRA_SECRETS_ENCRYPTION_SECRET_PREVIOUS to the old key for every process.
4. Start one application instance. Confirm its startup migration succeeds and an integration can read its credential before restoring the remaining replicas with the same configuration.
5. Remove the previous key in a later deployment, after rotation has completed.

Startup refuses a key that cannot decrypt existing secrets. Preserve the old key until rotation finishes.

HashiCorp Vault

HashiCorp Vault stores secret values externally instead of in the database. Only references to Vault secret paths are stored in PostgreSQL.

Set ARCHESTRA_SECRETS_MANAGER=VAULT, ARCHESTRA_HASHICORP_VAULT_ADDR, and an Enterprise license. Missing required configuration logs a warning and falls back to database storage. After rollout, confirm that Settings → Secrets appears and reports Connection Successful.

Set a custom storage prefix with ARCHESTRA_HASHICORP_VAULT_SECRET_PATH. ARCHESTRA_HASHICORP_VAULT_SECRET_METADATA_PATH overrides KV v2 metadata paths.

Vault Authentication

Choose the method matching your deployment identity using ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD.

The Vault configuration entries cover KV versions, custom auth mount points, token paths, and AWS endpoints.