Authorize A2A Peers with Per-Peer or Shared Tokens

Hermes supports named per-peer credentials through A2A_PEER_TOKENS and a shared credential through A2A_BEARER_TOKEN. Per-peer tokens provide the stronger operational model because the authenticated peer name can drive trust policy, rate limiting, and audit attribution.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/a2a

Prefer identity you can revoke

Use a separate token for each approved peer. Add authenticated names to A2A_TRUSTED_PEERS, keep A2A_ALLOW_ALL_USERS false, and set a sensible per-identity request limit. If one credential is exposed or a peer relationship ends, rotate or remove only that peer.

A shared bearer token is simpler but provides weaker attribution: the documented fallback identity is the caller IP. Do not assume undocumented behavior behind proxies, shared NAT, or load balancers. Use the shared path only when its limitations are acceptable and the network boundary is controlled.

Store tokens in the intended secret environment, not in config.yaml examples, prompts, screenshots, Agent Cards, or public logs. Credential-shaped strings are redacted from outbound replies as defense in depth, not as permission to pass secrets through peer conversations.

Authorization checklist

Create unique credentials for recurring peers.
Keep a reviewed trusted-peer allowlist.
Leave allow-all disabled outside disposable development.
Set a bounded per-identity rate limit.
Define rotation and revocation ownership.
Verify audit attribution without printing token values.

Common pitfalls

Using one shared token for every environment. One leak then affects all peers.
Treating caller IP as a stable person or service identity. Network topology can blur attribution.
Publishing raw audit records. Logs may contain operational metadata or message context.
Relying only on prompt filtering. Authentication and least-privilege tools remain necessary.

Verification

Test three cases: a valid trusted peer, an invalid token, and a valid-but-untrusted identity. Confirm the accepted request is attributed to the expected peer, rejected calls do not start agent work, and rate limiting is identity-scoped. Rotate one test token and verify the old value stops working without affecting another peer.