Vaults

Resolve upstream credentials at call time in Orca AI Gateway, so callers and agents never hold provider keys.

A vault is a named credential resolver. Destinations reference one by name, and the gateway resolves it at call time and injects the result upstream. The credential never appears in a response and is never returned to the caller.

vaults:
  - name: openai_key
    resolver: env
    env_var: OPENAI_API_KEY
    scheme: bearer

  - name: registry_vaults
    resolver: http
    url_template: "http://orca-registry:8081/internal/vaults/{credential_id}/resolve"
    timeout_ms: 5000

Resolvers

`resolver`	Where the credential comes from
`env`	A fixed environment variable, or one derived from the vault id.
`static_file`	A file on disk, read at startup.
`http`	An HTTP credential service, reached on cache miss or refresh.

An unrecognized resolver fails at boot with an error naming the vault and listing what is supported.

The gateway has no resolver for a cloud secret manager such as AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, or HashiCorp Vault. To use one, sync the secret into the environment or a mounted file, or front it with an http resolver.

env

vaults:
  - name: openai_key
    resolver: env
    env_var: OPENAI_API_KEY
    prefix: "ORCA_VAULT__"

env_var selects a fixed variable name. When it is omitted, the resolver derives the name from a prefix, an optional scope value, and the credential id:

Scope	Variable read
No `workspace_id` in scope	`ORCA_VAULT__openai_key`
`workspace_id=ws_42`	`ORCA_VAULT__ws_42__openai_key`

prefix defaults to ORCA_VAULT__. Namespacing by workspace_id is the default behavior, which is what lets one gateway serve per-tenant credentials from the environment.

static_file

vaults:
  - name: aws_creds
    resolver: static_file
    file: /var/lib/orca-gateway/credentials.yaml

The file is a YAML or JSON map keyed first by workspace_id and then by credential id:

credentials.yaml

ws_42:
  aws_creds:
    scheme: aws-sig-v4
    secret_value: 'AKIAEXAMPLE:secret-access-key:optional-session-token'
    ttl_seconds: 300
    version: "1"

scheme and secret_value are required. ttl_seconds defaults to 300, and version defaults to "1". The resolver loads this map at startup; changing its file requires a gateway restart.

http

vaults:
  - name: registry_vaults
    resolver: http
    url_template: "http://orca-registry:8081/internal/vaults/{credential_id}/resolve"
    bearer_token_file: /var/run/secrets/orca/registry/token
    timeout_ms: 5000

The template interpolates {credential_id} with the destination's logical credential and {scope.<dim>} with any scope dimension, so one vault entry can serve every credential a credential service holds. bearer_token_file, when set, supplies an Authorization bearer token and is reread for each backend call. This is how an Agent Engine integration resolves per-workspace MCP credentials from the registry.

timeout_ms defaults to 5000. Resolvers are cached by default, so an HTTP call happens on a cache miss, expiry, or an explicit refresh rather than on every request.

Cache and rotation

Every resolver is wrapped in a TTL cache unless you disable it:

vaults:
  - name: registry_vaults
    resolver: http
    url_template: "http://orca-registry:8081/internal/vaults/{credential_id}/resolve"
    cache:
      enabled: true
      ttl_secs: 300
      max_entries: 1024

The cache is keyed by scope and credential id. An HTTP resolver observes a rotated secret after its effective TTL expires, or when an MCP destination force-refreshes after an upstream 401 sent with Authorization. env reads a fixed process environment and static_file retains its startup map, so rotate either by restarting the gateway.

Destinations

Where a vault is referenced.

Security model

How secrets are held in memory and kept out of logs.