Skip to main content
API7.ai Logo

Upstream Authentication

Each registered Agent-to-Agent (A2A) agent can define how AISIX authenticates to the upstream agent. AISIX holds any upstream credential gateway-side and presents it when forwarding a call upstream. The caller API key an A2A client sends to AISIX authenticates the caller to AISIX and is never forwarded or exposed to the upstream agent.

Set the credential with the auth_type field and any fields required by that authentication mode when you register or update an agent. AISIX applies the same credential when it fetches the agent card and when it forwards JSON-RPC calls.

Authentication Modes​

Choose the mode that matches how the upstream agent expects AISIX to authenticate:

auth_typeUpstream credentialHow AISIX presents it
noneNoneNo credential is sent.
bearerBearer token in secretAuthorization: Bearer <secret>
api_keyAPI key in secretx-api-key: <secret>

The secret holds the plaintext credential AISIX presents upstream. It is used only gateway-side and is never sent to the calling client. To rotate a credential, update the resource with a new secret.

No Authentication​

Use none when the upstream agent does not require a credential, such as an agent reachable only on a trusted internal network.

The following example creates an agent resource without an upstream credential:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/a2a_agents" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "invoice-processor",
    "url": "https://agents.internal/invoice",
    "protocol_version": "0.3",
    "auth_type": "none"
  }'

auth_type defaults to none, so you can also omit it. Leave secret unset for a none agent.

Bearer Token​

Use bearer when the upstream agent expects a static token in the Authorization header.

The following example creates an agent resource with the bearer token AISIX should send upstream:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/a2a_agents" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "research-assistant",
    "url": "https://agents.example.com/a2a",
    "protocol_version": "0.3",
    "auth_type": "bearer",
    "secret": "YOUR_UPSTREAM_TOKEN"
  }'

❶ bearer sends Authorization: Bearer <secret> on every request to this upstream.

❷ secret is required and must be non-empty.

API Key​

Use api_key when the upstream agent expects a key in the x-api-key header.

The following example creates an agent resource with the API key AISIX should send upstream:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/a2a_agents" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "translator",
    "url": "https://agents.example.com/translate",
    "protocol_version": "0.3",
    "auth_type": "api_key",
    "secret": "YOUR_UPSTREAM_API_KEY"
  }'

❶ api_key sends x-api-key: <secret> on every request to this upstream.

❷ secret is required and must be non-empty.

Credential Handling​

The upstream credential never crosses to the calling client. The client presents only its AISIX caller API key, and AISIX forwards the request under the agent's configured credential.

If a credential later stops working, such as after a secret is rotated or revoked, only that agent's calls fail. Other registered agents keep working. AISIX returns HTTP 502; the upstream status appears only in the JSON-RPC error message, and the upstream response body is not proxied back.

The agent card AISIX serves includes the upstream agent's advertised metadata with the service url rewritten to the gateway. It does not include the upstream credential.

Next Steps​

You now understand how AISIX authenticates to upstream agents. Use these guides to control which callers can reach those agents and how their traffic is governed: