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_type`	Upstream credential	How AISIX presents it
`none`	None	No credential is sent.
`bearer`	Bearer token in `secret`	`Authorization: Bearer <secret>`
`api_key`	API key in `secret`	`x-api-key: <secret>`
`oauth2`	`client_id` + `token_url` + `secret`	Accepted on the resource, but not yet available for upstream authentication. See OAuth 2.0 Client Credentials.

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, 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.

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.

OAuth 2.0 Client Credentials

OAuth 2.0 client credentials are not yet available for upstream authentication.

AISIX accepts the oauth2 auth type on the agent resource for forward compatibility, but it does not exchange those credentials for an upstream access token yet.

The example below shows the accepted OAuth field shape. Calls to that agent return HTTP 501, and its agent card is not served until OAuth 2.0 upstream authentication is available.

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",
    "protocol_version": "0.3",
    "auth_type": "oauth2",
    "client_id": "aisix-gateway",
    "token_url": "https://auth.example.com/oauth/token",
    "secret": "YOUR_OAUTH_CLIENT_SECRET",
    "scopes": ["a2a.invoke"]
  }'

❶ oauth2 is accepted for forward compatibility. OAuth 2.0 upstream authentication is not available yet.

❷ client_id, token_url, and secret are required for an oauth2 agent. scopes is optional.

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:

Control agent access: scope caller API keys to specific agents or every agent.
Rate limits and budgets: apply request limits, concurrency limits, and budgets to A2A calls.
Observability: review the usage events and metrics emitted by A2A calls.

Authentication Modes​

No Authentication​

Bearer Token​

API Key​

OAuth 2.0 Client Credentials​

Credential Handling​

Next Steps​