Credentials¶
Agents that need credentials read them from request headers. a2a sends them from a flag, or asks a credential helper for them per agent.
| Option | Sends |
|---|---|
--auth "<value>" |
Authorization: <value> on every request. |
--svc-param key=value |
Any header, repeatable. key:value works too. |
--credential-helper [scope=]path |
The headers a helper program returns for the agent's URL. |
a2a auth get <url> |
Prints which helper answers for a URL and the header names it returns. |
a2a send -a https://agent.example.com --auth "Bearer $TOKEN" "hello"
a2a send -a https://agent.example.com --svc-param "X-API-Key=$KEY" "hello"
The same headers go with the card request, so a gateway that protects the card accepts them too. On gRPC they travel as metadata.
Credential helpers¶
A credential helper is a program that prints the headers for a URL. a2a uses the Bazel credential helper protocol, so helpers written for Bazel work. List them in ~/.config/a2a-cli/config.yaml:
credential-helper:
- command: [a2a-serve, credential] # every host
- scope: "*.corp.example.com"
command: [/usr/local/bin/corp-token, --audience, a2a]
The helper with the most specific matching scope runs. Its headers are cached until they expire, and --auth or --svc-param win over a header it returns. a2a-serve ships one: a2a-serve doctor --fix adds it, and it returns the tokens a2a-serve keeps for agents you started or joined.
a2a auth get https://agent.example.com # header names, values redacted
a2a auth get https://agent.example.com --reveal # header values
helper: a2a-serve credential
HEADER VALUE
Authorization <redacted>
A credential helper shows how to write one, and Credential helpers how they're chosen.
Storing secrets¶
config show redacts --auth and Authorization parameters, but a .env file stores them in plain text. Keep tokens in the environment, a private ~/.config/a2a-cli file, or a helper. --credential-helper is ignored when it comes from a project .env, so a cloned repository can't make a2a run a helper of its choice. Security lists what a project .env can set.