Gateway API Reference¶

The AIP gateway (cmd/gateway) is the HTTP interface for agent clients. It runs as a standalone binary alongside the controller and translates HTTP requests into Kubernetes CRD operations — agents do not need kubectl or a kubeconfig.

Starting the gateway¶

# Build
make build-gateway

# Run locally (uses ~/.kube/config by default)
./bin/gateway --addr :8080

Endpoints¶

Method	Path	Description
`POST`	`/agent-requests/{name}/approve`	Approve an AgentRequest
`POST`	`/agent-requests/{name}/completed`	Signal agent completed the action
`POST`	`/agent-graduation-policies`	Create an AgentGraduationPolicy
`POST`	`/agent-requests`	Submit an AgentRequest
`POST`	`/governed-resources`	Create a GovernedResource
`POST`	`/safety-policies`	Create a SafetyPolicy
`DELETE`	`/agent-graduation-policies/{name}`	Delete an AgentGraduationPolicy
`DELETE`	`/governed-resources/{name}`	Delete a GovernedResource
`DELETE`	`/safety-policies/{name}`	Delete a SafetyPolicy
`POST`	`/agent-requests/{name}/deny`	Deny an AgentRequest
`POST`	`/agent-requests/{name}/executing`	Signal agent started executing
`GET`	`/agent-graduation-policies/{name}`	Get an AgentGraduationPolicy by name
`GET`	`/agent-requests/{name}`	Get an AgentRequest by name
`GET`	`/agent-trust-profiles/{name}`	Get an AgentTrustProfile by name
`GET`	`/governed-resources/{name}`	Get a GovernedResource by name
`GET`	`/safety-policies/{name}`	Get a SafetyPolicy by name
`GET`	`/diagnostic-accuracy-summaries`	List DiagnosticAccuracySummaries
`GET`	`/agent-graduation-policies`	List AgentGraduationPolicies
`GET`	`/agent-requests`	List AgentRequests
`GET`	`/agent-trust-profiles`	List AgentTrustProfiles
`GET`	`/audit-records`	List AuditRecords
`GET`	`/governed-resources`	List GovernedResources
`GET`	`/safety-policies`	List SafetyPolicies
`POST`	`/mcp`	Proxy MCP tool calls via JSON-RPC 2.0 (native MCP protocol)
`POST`	`/mcp-proxy/{server}/{tool}`	Proxy MCP tool calls via REST (legacy, for non-MCP clients)
`GET`	`/mcp-registry`	List available MCP servers and their tools
`POST`	`/agent-requests/recompute-accuracy`	Trigger accuracy recomputation
`PUT`	`/agent-graduation-policies/{name}`	Replace an AgentGraduationPolicy
`PUT`	`/governed-resources/{name}`	Replace a GovernedResource
`PUT`	`/safety-policies/{name}`	Replace a SafetyPolicy
`PATCH`	`/agent-requests/{name}/verdict`	Submit a verdict (correct/incorrect)
`GET`	`/agent-requests/{name}/watch`	Watch an AgentRequest via SSE
`GET`	`/whoami`	Return current authenticated identity

All endpoints accept and return application/json. Pass ?namespace=<ns> to target a namespace other than default.

Example: submit an agent request¶

curl -s -X POST http://localhost:8080/agent-requests \
  -H "Content-Type: application/json" \
  -d '{
    "agentIdentity": "sre-agent-v1",
    "action": "restart",
    "targetURI": "k8s://production/deployment/payment-api",
    "reason": "OOMKilled 3 times in 10 minutes.",
    "correlationID": "incident-abc123",
    "namespace": "production"
  }'

Querying the full incident chain¶

When a correlationID is supplied to POST /agent-requests, the gateway stamps aip.io/correlationID on the resource as a label. The controller automatically propagates that label to every AuditRecord emitted for the request. Retrieve the complete chain with a single command:

kubectl get agentrequests,auditrecords \
  -n production \
  -l aip.io/correlationID=incident-abc123 \
  --sort-by=.metadata.creationTimestamp

Authentication¶

The gateway supports OIDC/JWT authentication. When enabled, every non-healthz request must carry a valid Authorization: Bearer <token> header. When disabled (default), the gateway falls back to proxy headers (X-Remote-User / X-Forwarded-User) injected by an upstream authenticating proxy.

Flags¶

Flag	Default	Description
`--oidc-issuer-url`	`""`	OIDC provider URL. When set, Bearer token validation is required. When unset, auth is disabled (dev/test only).
`--oidc-audience`	`aip-gateway`	Expected JWT `aud` claim.
`--oidc-identity-claim`	`sub`	JWT claim used as the agent identity.
`--agent-subjects`	`""`	Comma-separated JWT `sub` values permitted to create requests and transition state.
`--reviewer-subjects`	`""`	Comma-separated JWT `sub` values permitted to approve/deny requests and write verdicts.
`--admin-subjects`	`""`	Comma-separated JWT `sub` values permitted to manage `GovernedResource` and `SafetyPolicy`.
`--admin-groups`	`""`	Comma-separated JWT group claim values that grant admin role.
`--require-governed-resource`	`false`	When `true`, every `AgentRequest` must match a `GovernedResource` or it is rejected.
`--trusted-proxy-cidrs`	`""`	CIDRs from which `X-Remote-User`/`X-Forwarded-User` headers are accepted.

Authorization rules¶

Endpoint	Required role
`GET /healthz`, `GET /readyz`	None
`GET /whoami`	None
`GET /agent-requests`, `GET /agent-requests/{name}`	Any authenticated
`GET /agent-requests/{name}/watch`	Any authenticated
`POST /agent-requests`	`agent`
`POST /agent-requests/{name}/executing`	`agent` (creator only)
`POST /agent-requests/{name}/completed`	`agent` (creator only)
`POST /agent-requests/{name}/approve`	`reviewer`
`POST /agent-requests/{name}/deny`	`reviewer`
`PATCH /agent-requests/{name}/verdict`	`reviewer`
`POST /agent-requests/recompute-accuracy`	`reviewer`
`GET /audit-records`	Any authenticated
`GET /diagnostic-accuracy-summaries`	Any authenticated
`GET /agent-trust-profiles`, `GET /agent-trust-profiles/{name}`	`agent`, `reviewer`, or `admin`
`GET /mcp-registry`	Any authenticated
`POST /mcp-proxy/{server}/{tool}`	`agent` (AIP JWT in `X-AIP-Authorization` required for write tools; not required for read-only tools)
`POST /mcp`	`agent` (OIDC required in production; write tools additionally require AIP JWT in `X-AIP-Authorization`)
`POST /governed-resources`	`admin`
`GET /governed-resources`, `GET /governed-resources/{name}`	`admin`
`PUT /governed-resources/{name}`	`admin`
`DELETE /governed-resources/{name}`	`admin`
`POST /safety-policies`	`admin`
`GET /safety-policies`, `GET /safety-policies/{name}`	`admin`
`PUT /safety-policies/{name}`	`admin`
`DELETE /safety-policies/{name}`	`admin`
`POST /agent-graduation-policies`	`admin`
`GET /agent-graduation-policies`, `GET /agent-graduation-policies/{name}`	`admin`
`PUT /agent-graduation-policies/{name}`	`admin`
`DELETE /agent-graduation-policies/{name}`	`admin`

AIP JWT for write tools¶

Write tools (tools that modify state, such as create_pull_request) require a second, short-lived JWT sent via the X-AIP-Authorization header. This AIP JWT is distinct from the OIDC Authorization: Bearer token:

Authorization: Bearer <oidc-token> — authenticates the caller to the gateway (OIDC / proxy header).
X-AIP-Authorization: Bearer <aip-jwt> — authorizes a specific write action. The JWT is scoped to a single tool name, target repository, and request reference.

Read tools (tools that only query state, such as get_file_contents) do not require an AIP JWT — they only need the OIDC-level authentication.

To obtain an AIP JWT for a write tool, first submit an AgentRequest through the gateway, then approve it via POST /agent-requests/{name}/approve. The approve endpoint returns the signed JWT:

# 1. Submit an AgentRequest
curl -s -X POST http://localhost:8080/agent-requests \
  -H "Content-Type: application/json" \
  -d '{
    "agentIdentity": "my-agent",
    "action": "create_pull_request",
    "targetURI": "github://acme/demo/files/main/config.json",
    "reason": "Update config",
    "namespace": "default"
  }'

# 2. Approve the request (reviewer with X-Remote-User or OIDC)
curl -s -X POST "http://localhost:8080/agent-requests/<name>/approve?namespace=default" \
  -H "Content-Type: application/json" \
  -H "X-Remote-User: reviewer" \
  -d '{"reason": "approved"}'

# Response includes: {"token": "<aip-jwt>", "token_expires_at": "..."}

When calling a write tool via /mcp-proxy or POST /mcp, send both headers:

curl -X POST http://localhost:8080/mcp-proxy/github/create_pull_request \
  -H "Authorization: Bearer <oidc-token>" \
  -H "X-AIP-Authorization: Bearer <aip-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name":"create_pull_request","arguments":{"owner":"acme","repo":"demo"}}'

The MCP registry at GET /mcp-registry lists each tool's read_only field so clients can determine whether a call requires an AIP JWT. Tools with read_only: false are write tools and require the X-AIP-Authorization header.

Production setup (Helm)¶

Configure your OIDC provider to issue tokens with aud: aip-gateway.
Install with auth enabled:

helm upgrade --install aip-k8s \
  oci://ghcr.io/agent-control-plane/aip-k8s/charts/aip-k8s \
  --namespace aip-k8s-system --create-namespace \
  --set gateway.auth.oidcIssuerURL=https://accounts.google.com \
  --set gateway.auth.agentSubjects=<agent-service-account-sub> \
  --set gateway.auth.reviewerSubjects=sre1@example.com,sre2@example.com

Agents attach a Bearer token when calling the gateway. When auth is enabled, agentIdentity must equal the JWT sub claim:

TOKEN=$(gcloud auth print-identity-token --audiences=aip-gateway)
curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"agentIdentity":"<jwt-sub>","action":"restart","targetURI":"...","reason":"...","namespace":"production"}' \
     http://localhost:8080/agent-requests

Proxy-header fallback (no OIDC)¶

When --oidc-issuer-url is unset, the gateway reads X-Remote-User / X-Forwarded-User headers. To prevent header spoofing, restrict which source IPs may supply these headers:

./bin/gateway \
  --addr :8080 \
  --trusted-proxy-cidrs 10.0.0.0/8,172.16.0.0/12 \
  --agent-subjects sre-agent \
  --reviewer-subjects sre@example.com