Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/archestra-ai/archestra/llms.txt

Use this file to discover all available pages before exploring further.

Archestra stores sensitive data — API keys, OAuth tokens, and MCP server credentials — as secrets. By default, secrets are encrypted at rest in the database using AES-256-GCM. For enterprise deployments that require an external secrets store, Archestra integrates with HashiCorp Vault, keeping only path references in the database while all secret values live in Vault.
Existing secrets are not migrated when you change the secrets manager. Recreate all secrets after switching between storage backends.

​
Storage Backends

Archestra supports three secrets manager modes controlled by the ARCHESTRA_SECRETS_MANAGER environment variable.

DB

Default mode. Secrets are encrypted at rest in the Archestra database using AES-256-GCM. The encryption key is derived from ARCHESTRA_AUTH_SECRET. No external dependencies required.

VAULT

Enterprise mode. Secret values are stored in HashiCorp Vault. Archestra reads, writes, and deletes them in Vault; only references to secret paths stay in the database.

READONLY_VAULT

Read-only Vault mode. Archestra reads existing secrets from Vault but does not write or delete. Use when secrets are managed externally and Archestra should only consume them.

​
Database Storage

Database storage is active by default. To configure it explicitly, set: 
ARCHESTRA_SECRETS_MANAGER=DB
Secrets are automatically encrypted using AES-256-GCM. The encryption key is derived from your ARCHESTRA_AUTH_SECRET environment variable. Encryption and decryption are fully transparent — no additional configuration is needed. Existing plaintext secrets are automatically migrated to encrypted format on startup.
Do not change ARCHESTRA_AUTH_SECRET after deployment. Rotating this value will:
  • Invalidate all user sessions (forcing re-login)
  • Make all existing encrypted secrets unreadable
  • Break JWT signing (JWKS private keys are encrypted with this secret)
  • Break two-factor authentication for enrolled users

​
HashiCorp Vault

HashiCorp Vault integration is an enterprise feature. Contact sales@archestra.ai for licensing information.
In Vault 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.

​
Core Environment Variables

VariableRequiredValue
ARCHESTRA_SECRETS_MANAGERYesVAULT
ARCHESTRA_HASHICORP_VAULT_ADDRYesYour Vault server address
ARCHESTRA_ENTERPRISE_LICENSE_ACTIVATEDYesYour license value
ARCHESTRA_HASHICORP_VAULT_AUTH_METHODNoTOKEN (default), K8S, or AWS
ARCHESTRA_HASHICORP_VAULT_KV_VERSIONNo1 or 2 (default: 2)
ARCHESTRA_HASHICORP_VAULT_SECRET_PATHNoPath prefix for stored secrets
ARCHESTRA_HASHICORP_VAULT_SECRET_METADATA_PATHNoOverride path prefix for KV v2 metadata operations
If ARCHESTRA_SECRETS_MANAGER is set to VAULT but the required environment variables are missing, the system falls back to database storage automatically.

​
Secret Storage Paths

Vault paths are built as {prefix}/{secretName}. A secret named github_token is written to {prefix}/github_token. The ARCHESTRA_HASHICORP_VAULT_SECRET_PATH variable sets the prefix; its default depends on the configured KV engine version.
KV VersionDefault PrefixResolved Path
2secret/data/archestrasecret/data/archestra/{secretName}
1secret/archestrasecret/archestra/{secretName}
For KV v2, list and delete operations use a metadata path derived from ARCHESTRA_HASHICORP_VAULT_SECRET_PATH by swapping /data/ for /metadata/: 
kv/data/platform/archestra  →  kv/metadata/platform/archestra
Only set ARCHESTRA_HASHICORP_VAULT_SECRET_METADATA_PATH when your metadata prefix does not follow this /data/ ↔ /metadata/ convention.

​
Example: Reading Database URL from a Custom Vault Path

# Store the secret in Vault at a custom path
ARCHESTRA_HASHICORP_VAULT_SECRET_PATH=kv/data/production/archestra

# A secret named "database_url" will be read from:
# kv/data/production/archestra/database_url

# KV v2 metadata operations will use:
# kv/metadata/production/archestra/database_url

​
Vault Authentication

Archestra supports three authentication methods for connecting to HashiCorp Vault.
The simplest authentication method. Provide a static Vault token directly.
VariableRequiredDescription
ARCHESTRA_HASHICORP_VAULT_TOKENYesVault authentication token
ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD=TOKEN
ARCHESTRA_HASHICORP_VAULT_TOKEN=hvs.your-vault-token

​
Full Vault Configuration Example

The following shows a complete Kubernetes deployment configuration using KV v2 and K8S authentication: 
# Storage backend
ARCHESTRA_SECRETS_MANAGER=VAULT
ARCHESTRA_ENTERPRISE_LICENSE_ACTIVATED=your-license-value

# Vault connection
ARCHESTRA_HASHICORP_VAULT_ADDR=https://vault.internal.example.com:8200
ARCHESTRA_HASHICORP_VAULT_KV_VERSION=2

# Custom secret path (team-scoped)
ARCHESTRA_HASHICORP_VAULT_SECRET_PATH=kv/data/teams/platform/archestra

# Kubernetes authentication
ARCHESTRA_HASHICORP_VAULT_AUTH_METHOD=K8S
ARCHESTRA_HASHICORP_VAULT_K8S_ROLE=archestra-production
With this configuration, a secret named openai_api_key is stored at: 
kv/data/teams/platform/archestra/openai_api_key
And KV v2 metadata operations use: 
kv/metadata/teams/platform/archestra/openai_api_key

​
Team-Scoped Vault Folders for MCP Server Credentials

When multiple teams share an Archestra deployment, MCP server credentials can be stored under team-scoped Vault path prefixes. This ensures that credentials belonging to one team’s MCP servers are isolated from other teams at the Vault policy level, and Archestra reads only the paths it is authorized to access for each team context.
Use Vault’s policy engine to restrict which Archestra service accounts can read which path prefixes. For example, grant the platform-team Archestra role read access only to kv/data/teams/platform/* and the data-team role only to kv/data/teams/data/*.

Build docs developers (and LLMs) love

Get started for freeTalk to us