Trace Credential Provenance from Secret Source to Pool

A successful model call does not prove that Hermes used the intended credential. The runtime may have selected a local key, an externally resolved reference, another credential in the same-provider pool, or a cross-provider fallback. Provenance turns that ambiguity into an auditable chain.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools

Follow the chain without exposing values

At startup, secret sources attach an origin label to each resolved variable. Provider resolution can then seed a credential-pool entry from that environment reference. Borrowed runtime secrets should remain reference-only at the durable pool boundary: metadata, status, counters, source reference, and a non-reversible fingerprint may persist, while the resolved secret stays in memory for that run.

Same-provider pool rotation and cross-provider fallback are separate events. A rate or billing failure can move the active credential, and switching account keys can also lose provider-side prompt-cache benefits. Audit status after the actual workload, not only immediately after startup.

Provenance checklist

Record the expected source for every provider credential.
Confirm startup labels match the source policy.
Use hermes auth list to inspect pool entries and the active marker.
Verify borrowed external secrets persist as references, not raw values.
Distinguish same-provider rotation from provider fallback.
Review cooldown or exhausted state after rate and billing errors.
Reset cooldowns only after the underlying condition is understood.
Keep redacted audit evidence free of token values and personal vault names.

Common pitfalls

Treating a provider response as proof of which key was used.
Manually adding a credential when a managed reference was intended.
Assuming pool rotation and fallback have the same cost and security effect.
Persisting a borrowed vault value into auth.json instead of its source reference.
Resetting exhaustion state repeatedly while the provider quota is still closed.
Printing fingerprints as though they were reversible secrets—or printing real tokens for comparison.

Verification steps

Start a fresh process and capture variable names plus provenance labels only.
Run hermes auth list and confirm the expected provider pool and active entry.
Inspect durable metadata to verify external values are reference-only.
Exercise one controlled same-provider rotation and observe the active marker change.
If a fallback is configured, test it separately and record the provider transition.
Restart Hermes and confirm auto-discovered entries update while manual entries remain intentional.
Save a redacted report that connects source, pool entry, active identity, and verification result.