credential_inject

Replaces caller credentials with the upstream credential selected by intelligent_route or provider_route.
On this page

Replaces caller credentials with the upstream credential selected by intelligent_route or provider_route.

Configuration Notes

Reads intelligent_route.credential.* filter metadata written by the preceding routing filter, looks up the configured token, removes caller authorization, and sets exactly one provider credential header (a bearer Authorization value, or the raw token in the configured header for apikey). Token values are never written to metadata, traces, or error bodies. See the module documentation for the complete data flow and configuration.

Configuration

FieldTypeRequiredDescription
credentialsCredentialEntryConfig[]noCredential entries, keyed by secretRef (name/namespace/key). May be empty only when projected_credential_mount_base is configured.
credentials[].namestringyesKubernetes Secret name — must match intelligent_route.credential.name.
credentials[].namespacestringyesKubernetes Secret namespace — must match intelligent_route.credential.namespace.
credentials[].keystringyesKey within Secret.data — must match intelligent_route.credential.key.
credentials[].strategystringnoCredential strategy. Supports "bearer_token" (injects Authorization: Bearer <token>) and "apikey" (injects the raw token into header).
credentials[].headerstringnoInjection header for strategy: apikey. Defaults to x-api-key. Mutually exclusive with strategy: bearer_token, which always injects Authorization. Reserved internal header prefixes (x-praxis-, x-mcp-), transport-controlled names (host, content-length, hop-by-hop, proxy-authorization), and authorization itself are rejected: the Praxis upstream boundary would strip the injected credential in flight, and transport-controlled targets would corrupt framing or leak the credential to an intermediary.
credentials[].valuestringnoInline token value. Mutually exclusive with env_var and file.
credentials[].env_varstringnoEnvironment variable holding the token. Mutually exclusive with value and file.
credentials[].filestringnoPath to a file containing the token. The initial value is validated at filter construction. A watcher revalidates the file after atomic projected-volume changes so Secret rotation does not require a restart. The file contents are trimmed of leading/trailing whitespace before use. The file must exist, be readable, and be non-empty; construction fails otherwise. Use this source when the token is mounted from a Kubernetes Secret volume so that token bytes never appear in Praxis ConfigMaps. Mutually exclusive with value and env_var.
projected_credential_mount_basePathBufnoOptional root containing projected Secret directories. When configured, a credential reference selected from a live routing overlay may be resolved from {root}/{namespace}/{secret-name}/{secret-key} even when it was not present in the startup credential table. Including the namespace keeps same-name Secrets distinct. Projected apikey entries use x-api-key; providers requiring another header need a configured credential entry. This lets a no-route startup safely accept later credential-bearing overlay revisions: an absent or unmounted file rejects the request with 503 after the 250 ms cache refresh interval. A rotated or revoked token may be used until that interval expires. Overlay digest and scope validation do not authenticate the publisher: use only a trusted publisher and mount only Secrets this gateway is authorized to inject. The root must be read-only to untrusted processes; concurrent symlink rewriting is outside the containment guarantee.

Example

filter: credential_inject
credentials:
  - name: my-api-secret        # matches intelligent_route.credential.name
    namespace: grid-system      # matches intelligent_route.credential.namespace
    key: token                  # matches intelligent_route.credential.key
    strategy: bearer_token      # optional, defaults to bearer_token
    file: /run/secrets/grid-credentials/my-api-secret/token
  - name: other-secret
    namespace: default
    key: api-key
    strategy: apikey            # raw token in a header instead of Authorization
    header: x-api-key           # optional, defaults to x-api-key
    env_var: OTHER_API_TOKEN    # token from environment variable