Skip to main content
API7.ai Logo

Upstream Authentication

Each registered Agent-to-Agent (A2A) agent defines whether and how AISIX authenticates to its upstream. AISIX presents the configured credential, if any, when fetching the agent card or forwarding a JSON-RPC call. Clients authenticate to AISIX with a caller API key, which is never forwarded upstream.

This separation lets each upstream use the authentication scheme it requires while callers keep one AISIX credential. AISIX Cloud and the open-source AISIX gateway support the same modes through different management paths.

Prerequisites​

Complete Set Up Agent Gateway for AISIX Cloud or the open-source AISIX gateway. Keep the shell, gateway, and test agent running if you want to adapt the example.

Authentication Modes​

Choose the mode that matches what the upstream agent expects:

auth_typeRequired fieldUpstream header
noneNoneNo credential is sent.
bearersecretAuthorization: Bearer <secret>
api_keysecretx-api-key: <secret>

auth_type defaults to none. Leave secret unset in that mode. A nonempty secret is required for bearer and api_key.

Use HTTPS for a credentialed upstream. When a bearer token or API key is configured on an http:// URL, the gateway logs a warning because the credential crosses the network in plaintext.

Configure Upstream Authentication​

The following examples change the setup guide's echo-agent to use a bearer token. The test agent does not validate credentials, so use a credentialed upstream to verify authentication end to end. Use api_key instead when the upstream expects x-api-key.

AISIX Cloud​

Export the credential, then update the registered agent:

export A2A_AGENT_TOKEN="YOUR_UPSTREAM_TOKEN"

curl -fsS -X PATCH "$AISIX_CP/a2a_agents/$A2A_AGENT_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF | jq
{
  "auth_type": "bearer",
  "secret": "${A2A_AGENT_TOKEN}"
}
EOF

The credential is write-only: AISIX Cloud encrypts it at rest and does not include it in create, list, or update responses. Sending a new secret rotates the credential. Changing from a credentialed mode to none clears the stored credential.

Open-Source AISIX Gateway​

Reference a gateway environment variable from the agent entry in resources.yaml:

resources.yaml
a2a_agents:
  - name: echo-agent
    url: http://aisix-a2a-echo:8080
    protocol_version: "1.0"
    auth_type: bearer
    secret: ${A2A_AGENT_TOKEN}

Set A2A_AGENT_TOKEN in the gateway process environment before loading the file. An unset or empty referenced variable causes validation to fail. If the variable is already available in the running container, validate the complete file and send SIGHUP:

docker exec aisix-quickstart \
  aisix validate --resources /etc/aisix/resources.yaml

docker kill --signal HUP aisix-quickstart

Adding or changing a container environment variable requires recreating that container with the new value. See Reload a Resources File for the validation and recreation workflow.

Credential Failures​

The upstream credential never crosses to the calling client. The agent card served by AISIX contains the upstream agent's metadata with service URLs rewritten to the gateway, but it does not contain the configured credential.

If an upstream rejects an expired, rotated, or revoked credential, only calls to that agent fail. AISIX returns HTTP 502; the upstream status appears in the JSON-RPC error message, and the upstream response body is not proxied to the caller.

Next Steps​

You have now configured how AISIX authenticates to an upstream agent. Use these guides to control callers and traffic: