docs/platform/infrastructure/external-vaults.md
By default, Encore Cloud stores your application's secrets in the Encore vault and copies them into your cloud provider's secret manager during deploys, so they're available to your application at runtime. External vaults let you go a step further and reference secrets that already live in an external secret store, so the secret value never has to be entered into or stored by Encore Cloud.
This is useful when secrets are owned by another team or system, managed by an existing rotation process, or required by policy to stay in a specific secret store.
<Callout type="info">External vaults are an Enterprise feature. Contact us to enable them for your organization.
</Callout>You connect a vault to your Encore app, pointing it at an external secret store. Individual secrets can then be configured to reference a secret in that vault — by its name and version — instead of holding a value managed by Encore. At runtime, your application reads the value directly from the external store.
| Provider | Status |
|---|---|
| GCP Secret Manager | Available. Reference secrets stored in Google Cloud Secret Manager. |
| AWS Secrets Manager | In active development — reach out if you're interested. |
Vaults are configured at the app level. You need the Admin or Member (owner/writer) role, and the feature must be enabled for your organization.
To connect a GCP Secret Manager vault you'll provide:
You then need to grant the connected account access to the secrets. In the GCP project that holds the secrets:
secretmanager.secrets.getIamPolicysecretmanager.secrets.setIamPolicyThe dashboard shows the exact account email and permissions, with copy-to-clipboard helpers, while you're filling in the configuration.
Notice that the connected account only needs getIamPolicy and setIamPolicy — not access to the secret values themselves. Encore Cloud uses these permissions to grant your application's runtime service accounts access to the referenced secrets; it never needs to read the values itself.
Because the connected account holds setIamPolicy, it could in principle grant itself (or another principal it controls) access to the secret values. If your security model requires that Encore Cloud is able to manage access but never able to read the secrets, you can enforce that with two GCP IAM deny policies.
Deny policies take precedence over allow policies, so they hold even if an allow binding is later added. Attach them at the project, folder, or organization level that contains the secrets.
This deny policy blocks the access permission on Secret Manager for every principal except the service accounts that belong to your production project(s). Even if Encore's connected account granted itself an allow binding, this deny rule would override it — only your runtime workloads can read the values.
Replace 123456789012 with the numeric project ID of the project whose service accounts are allowed to read the secrets (add an exceptionPrincipals entry per production project):
{
"displayName": "Strict App Project Boundary for Secrets",
"rules": [
{
"denyRule": {
"deniedPrincipals": ["principalSet://goog/public:all"],
"exceptionPrincipals": [
"principalSet://cloudresourcemanager.googleapis.com/projects/123456789012/type/ServiceAccount"
],
"deniedPermissions": ["secretmanager.googleapis.com/*.access"]
}
}
]
}
The boundary above relies on only your production service accounts being able to read secrets. To prevent Encore's connected account from sidestepping it by impersonating one of those accounts, deny it the Service Account Credentials impersonation permissions.
Replace the deniedPrincipals entry with the principal identifier of your Encore connected/orchestrator service account:
{
"displayName": "Block Encore Orchestrator Impersonation Loophole",
"rules": [
{
"denyRule": {
"deniedPrincipals": ["principal://goog/subject/app-1esdad@..."],
"deniedPermissions": [
"iam.googleapis.com/serviceAccounts.getAccessToken",
"iam.googleapis.com/serviceAccounts.getOpenIdToken",
"iam.googleapis.com/serviceAccounts.signBlob",
"iam.googleapis.com/serviceAccounts.signJwt",
"iam.googleapis.com/serviceAccounts.implicitDelegation"
]
}
}
]
}
With both policies in place, Encore Cloud can still manage which runtime identities are allowed to read each secret, but cannot read the secret values itself — directly or via impersonation.
<Callout type="warning">Make sure the exceptionPrincipals in the first policy cover every service account your application actually runs as, otherwise your workloads will be denied access to the secret values too.
External vault support for AWS (including AWS Secrets Manager) is in active development.
If you're running on AWS and want to reference secrets from an external store, reach out — we'd love to hear about your use case and can let you know when AWS support is available.
Once a vault is connected, you can point a secret at it instead of storing a value in Encore:
Your application keeps reading the secret by name in code — only the source of the value changes. Different environments can reference different vaults or versions, just like regular secrets.
From the External Vaults section you can: