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.

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

Configure authentication using one of the methods described in 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

Secrets are stored using the KV secrets engine v2:

• Data path: secret/data/archestra/{secretName}

Readonly Vault

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

Readonly Vault enables teams to use secrets from their organization's external HashiCorp Vault without Archestra managing those secrets. In this mode, Archestra only reads secrets from Vault at runtime—it never creates, updates, or deletes secrets in your Vault.

Environment Configuration

To enable Readonly Vault, configure the following environment variables:

Configure authentication using one of the methods described in Vault Authentication.

Connecting a Team to a Vault Folder

Each team in Archestra should be linked to a specific vault folder to use external secrets. Team members can then use secrets from that folder when installing MCP servers.

Example: Connecting a Team

To connect a team to a Vault folder at kv/platform/ee/archestra:

1. Navigate to Settings → Teams
2. Find your team and click the Configure Vault Folder button

3. Enter the path: kv/platform/ee/archestra
4. Click Test Connection to verify access
5. Click Save Path

Using Vault Secrets with MCP Servers

Once a team is connected to a Vault folder, team members can select secrets from Vault when installing MCP servers.

Example: Creating a GitHub MCP Server with Vault Secret

This example shows how to install a remote GitHub MCP server using a personal access token stored in Vault at ghtoken with the key token:

1. Navigate to MCP Catalog
2. Find the GitHub MCP server and click Install
3. Select the team with the configured Vault folder
4. In the authentication section, select Use Vault Secret
5. From the Secret dropdown, select ghtoken
6. From the Key dropdown, select token
7. Complete the installation

The MCP server will now use the secret value from your Vault at runtime.

Required Vault Permissions

Ensure your Vault policy grants Archestra read access to the configured paths:

# For KV v2
path "<mount>/data/<path>/*" {
  capabilities = ["read", "list"]
}

path "<mount>/metadata/<path>/*" {
  capabilities = ["read", "list"]
}

# For KV v1
path "<mount>/<path>/*" {
  capabilities = ["read", "list"]
}

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