External credential injection
External credential injection authenticates approved external HTTP calls at a Consul terminating gateway. External Model Context Protocol (MCP) servers are the primary use case, and the same mechanism applies to other approved external HTTP APIs that accept a bearer token or API key, such as a hosted model inference API. Provider credentials remain at the egress point that needs them instead of being distributed to agent applications.
You enable credential injection in a terminating gateway configuration entry. A Vault Agent sidecar delivers each credential to the gateway's local authentication processor. To learn how model, tool, and identity paths fit together, refer to the Consul Agentic Runtime Fabric architecture.
Enterprise
This feature requires Consul Enterprise. Refer to the Enterprise feature matrix for additional information.
Introduction
External MCP services and APIs can require a bearer token or API-key header even when callers already have Consul workload identities. These credentials solve a different problem from mesh authorization: they authenticate the gateway to the external provider.
The architecture separates two inputs:
| Input | Owner | Information supplied |
|---|---|---|
| Route and authorization | Consul configuration plane | Approved destination, mesh policy, external TLS settings, and a non-secret credential-binding identifier. |
| Credential delivery | Vault and the gateway-local credential runtime | Credential material for the fixed binding, with validity and rotation information. |
Consul does not fetch the provider credential from Vault for inclusion in proxy configuration. Vault does not publish provider secrets into Consul. A gateway-local authentication processor connects the trusted route binding to the delivered credential.
Authorized request path
An in-mesh caller, such as the MCP Gateway routing an approved tool request or an agent workload calling an external API, reaches the external service through a configured upstream. Mesh connectivity carries the call to the terminating gateway, where workload authentication and applicable intentions precede credential injection.
Consul writes the credential-binding identifier into the terminating gateway's route configuration, and Envoy passes it to the local authentication processor. The processor removes any authentication or binding headers that the caller sent, then sets only the configured authentication header. Envoy rejects any other header mutation from the processor, so the processor cannot change the destination, path, or route.
The terminating gateway connects to the external service over TLS and verifies the server certificate against the configured CA and server name. TLS is required: Consul rejects a terminating-gateway configuration that enables credential injection for a service without a CA file and a DNS server name (SNI), so a provider credential is never sent over plaintext. The external service must also use an HTTP-based protocol. The gateway forwards the authenticated request only when both the route and its credential are usable.
Supported authentication headers
Each binding injects exactly one of the following headers:
| Header | Value sent to the external service |
|---|---|
authorization | Bearer <credential> |
authorization | apikey <credential> |
x-api-key | <credential> |
x-goog-api-key | <credential> |
api-key | <credential> |
Trusted bindings
Operators bind a logical destination to an approved external endpoint, authentication-header policy, and credential source. A caller cannot select a Vault path, provider account, credential-binding identifier, header name, or external TLS server name.
Binding metadata comes only from Consul configuration. Binding headers sent by a caller are removed before the request leaves the gateway, so credential injection cannot send an approved provider credential to a host that the caller selects.
Only the processes that need credential material can read it. Applications and the MCP Gateway never receive provider secrets. The authentication processor can read rendered credentials but not the Vault Agent's authentication token.
Credential delivery
A Vault Agent sidecar on the terminating gateway authenticates to Vault with the gateway's Kubernetes service account and renders each binding's credential to a memory-backed volume that only the authentication processor reads. Credentials are never written to persistent storage. The Vault Agent connects to Vault over HTTPS and verifies the Vault server certificate against a configured CA.
Store each binding's credential as a Vault KV secret with the following fields:
| Field | Required | Description |
|---|---|---|
value | Yes | The provider credential. It must be non-empty and must not contain whitespace or control characters. |
rotation_deadline | Yes | UTC timestamp in RFC 3339 format, ending in Z, by which you must rotate the credential. |
expires_at | No | UTC timestamp in RFC 3339 format, ending in Z, when the provider credential expires. |
The Vault KV version identifies the credential generation, so each write to the secret creates a new generation. A credential stops being usable shortly before the earlier of rotation_deadline and expires_at, even if Vault is unavailable and no newer credential arrives.
Readiness and rotation
Processor readiness and destination credential readiness are distinct. A running processor does not establish that every binding has a usable credential. A missing, invalid, or expired credential must fail the affected call closed rather than forward it without authentication.
To rotate a credential, write a new version of its Vault KV secret. The Vault Agent renders the update and the authentication processor picks it up without restarting the gateway. The credential runtime validates each update and replaces the active credential without exposing partially written values. An older generation never overwrites a newer accepted credential.
An outage does not authorize indefinite use of cached credentials. The last valid credential remains usable only until its rotation deadline or expiry, as described in Credential delivery. A problem with one binding does not prevent unrelated, valid bindings from serving requests.
Observe binding health independently of the overall gateway process health. The authentication processor logs a credential_reload event for each binding with the accepted kv_version and an outcome such as accepted, unavailable, expired, or rejected. It also periodically logs a credential_status event that reports whether each binding is usable and how many seconds of validity remain.
Security guarantees
- Provider credentials and Vault tokens stay out of agent configuration, Consul configuration, proxy configuration snapshots, logs, traces, and error messages.
- Credential mutations are limited to the configured authentication header. They cannot change the route or disable external TLS verification.
- Binding status, policy outcomes, and rotation failures are logged without secret values.
- Caller authorization checks still apply when a provider credential is available.
Dependencies and boundaries
External credential injection covers external HTTP services, including MCP servers and other APIs, that use one of the supported authentication headers with a credential backed by Vault. It depends on an approved terminating-gateway route, protected credential delivery, a local authentication processor, and verified external TLS.
This component owns credential delivery, injection, readiness, and rotation for that scope. It does not define managed-model authentication, OAuth delegation, request signing, client-certificate authentication, arbitrary secret managers, or non-HTTP MCP transports.