Control Agent Access Per Key

A caller API key's allowed_agents decides which A2A agents that key can reach. The gateway checks it on every A2A request — both the JSON-RPC call at /a2a/<agent> and the agent-card fetch at /a2a/<agent>/.well-known/agent-card.json — and rejects an agent the key does not allow before it contacts the upstream agent.

A key with no allowed_agents — omitted, null, or an empty list — can reach no A2A agent. Access is granted explicitly.

Each A2A agent is one addressable unit identified by its display_name. A grant therefore lists agent names directly, not the <server>__<tool> pairs used for MCP tools.

Matching Rules

Each allowed_agents entry is matched as a single-* glob against the agent's display_name:

Entry	Grants	Example
Exact name	One specific agent.	invoice-processor allows only that agent.
*	Every registered agent.	* allows all current and future agents.

Choose the narrowest access that fits the caller. List each agent the caller needs by exact name, or use * for a key that may reach every agent.

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_agents": ["invoice-processor", "research-assistant"]
  }'

This key can reach the invoice-processor and research-assistant agents, and nothing else.

Advanced matching

Because entries are single-* globs — the same matcher as allowed_tools — a * can appear inside a pattern, so invoice-* grants every agent whose name starts with invoice-. Prefer exact names or * unless you specifically want a prefix pattern.

Update a Key's Agent Access

Updates replace the resource, so include the existing key hash and any other fields you want to keep, along with the new allowed_agents:

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/apikeys/YOUR_API_KEY_ID" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_agents": ["invoice-processor"]
  }'

To revoke all A2A agent access for a key, set allowed_agents to []. The key keeps its model access and other settings but can no longer reach any agent.

How Enforcement Works

The gateway checks allowed_agents on every A2A request, after confirming the agent exists and is enabled:

• An unknown or disabled agent returns 404.
• A known agent the key does not allow returns 403, before AISIX contacts the upstream agent.
• A known agent the key allows is forwarded upstream.

The same check gates the agent-card endpoint, so a caller can neither invoke nor discover the card of an agent outside its grant. Because the existence check runs first, an authenticated caller can tell an agent it lacks access to (403) apart from one that does not exist (404); scope access with allowed_agents accordingly.

Manage Agent Access on AISIX Cloud

On AISIX Cloud, you set agent access from the caller API key form in the dashboard instead of the Admin API. Grant the key every A2A agent, or select individual agents exposed to the key's environment. The stored grant maps back to these controls when you edit the key. See AISIX Cloud.

Next Steps

• Upstream authentication — configure how AISIX authenticates to each agent.
• Agent Gateway Overview — register an agent and reach it end to end.
• Caller API Keys — manage caller credentials.