Upstream Authentication

Each registered A2A agent carries the credential AISIX uses to authenticate to that upstream agent. AISIX holds this credential on the gateway side and presents it when it forwards a call upstream. The caller API key an A2A client sends to AISIX authenticates the caller to AISIX — it is never forwarded to, or exposed to, the upstream agent's caller.

Set the credential with the auth_type field (and its companion fields) when you register or update an agent. AISIX applies the same credential to both operations it performs against the upstream: fetching the agent card and forwarding JSON-RPC calls.

auth_type	Upstream credential	How AISIX presents it
none	None	No credential is sent.
bearer	secret (a bearer token)	Authorization: Bearer <secret>
api_key	secret (an API key)	x-api-key: <secret>
oauth2	client_id + token_url + secret	Accepted on the resource but not yet served — see below.

The secret holds the plaintext credential AISIX must present 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 (for example, an agent reachable only on a trusted internal network).

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, client_id, token_url, and scopes unset for a none agent.

Bearer Token

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

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"
  }'

AISIX sends Authorization: Bearer YOUR_UPSTREAM_TOKEN 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. Put the key in secret.

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"
  }'

AISIX sends x-api-key: YOUR_UPSTREAM_API_KEY on every request to this upstream. secret is required and must be non-empty.

OAuth 2.0 Client Credentials (Not Yet Available)

The oauth2 auth type is accepted on the agent resource for forward compatibility, but the data-plane runtime does not yet mint the token. You can create an oauth2 agent — supplying client_id, token_url, and the OAuth client secret in secret — but a call to it returns HTTP 501, and its agent card is not served.

# Accepted at write time, but calls to this agent return 501 until the
# runtime implements the OAuth 2.0 client credentials grant.
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": "orders",
    "url": "https://agents.example.com/orders",
    "auth_type": "oauth2",
    "client_id": "aisix-gateway",
    "token_url": "https://auth.example.com/oauth/token",
    "secret": "YOUR_OAUTH_CLIENT_SECRET",
    "scopes": ["a2a.invoke"]
  }'

Until the runtime supports it, use bearer or api_key for authenticated agents.

Validation Rules

AISIX validates the credential fields against auth_type when you create or update an agent:

• none — leave secret, client_id, token_url, and scopes unset.
• bearer / api_key — secret is required and must be non-empty.
• oauth2 — client_id, token_url, and secret are all required and must be non-empty; scopes is optional. The resource is accepted, but calls return 501 (see above).

An agent that fails these rules is rejected at write time with HTTP 400. A display_name that contains / is rejected, because it is the agent's URL path segment. A duplicate display_name is rejected with 409.

If a credential later stops working (for example, a rotated or revoked secret), that agent's calls fail while other registered agents keep working. The failure is logged as a bad-gateway (502) upstream error, and no credential detail reaches the calling client.

Credential Isolation

The upstream credential never crosses to the calling client:

• The client presents only its AISIX caller API key. AISIX authenticates the caller with it and forwards the request to the upstream agent under the agent's own configured credential.
• On an upstream failure, AISIX returns HTTP 502; the upstream status appears only in the JSON-RPC error message, and the response body is not proxied back.
• The agent card AISIX serves carries the upstream agent's advertised metadata with the service url rewritten to the gateway; it does not carry the upstream credential.

Next Steps

• Control agent access per key — decide which callers may reach each agent.
• Agent Gateway Overview — register an agent and reach it end to end.
• Rate limits and budgets — throttle and cap A2A calls on the caller API key.