Broker and gateway endpoints

These endpoints are not called by people or browsers. They are how agents and services reach a model, and how the control plane gets a certificate for a task. They are kept out of the browser API reference on purpose, and the route-drift test lists them as internal (api/internal-routes.yaml, group broker-gateway).

In plain words

An agent never holds a model key. It sends its model request to the gateway over a task certificate. The gateway checks the request, records usage, and passes it to the broker, which is the only service that holds the provider key and adds it on the way out. The broker also issues the short-lived task certificates.

Model gateway (port 8082, published as 443)

Route	Caller	What it does
POST /v1/messages	The agent's model bridge, with a task certificate	Anthropic Messages shape. The request must name the exact configured model, carry the literal placeholder forelead-no-credential as the API key, and use only the tool set registered for the task. Server tools, file IDs, uploads and code execution are refused.
POST /v1/responses	The same	OpenAI Responses shape, for models mapped with "provider":"openai" or "azure-openai" (mappings).

The gateway reads the workspace and task from the mTLS certificate, meters usage into model_usage (fresh input, cache read and cache write tokens are separate), and refuses a request the task's contract does not allow. A refusal is logged as model tool refusal with the request hash.

Credential broker (port 8083)

Route	Caller	What it does
POST /v1/model/invoke	The gateway	Generic model mapping. Does not support Anthropic.
POST /v1/model/messages	The gateway	Anthropic Messages. The broker puts the customer key in the upstream x-api-key.
POST /v1/model/responses	The gateway	OpenAI Responses.
GET /v1/model-list/{vendor}	The model watcher	Reads a vendor's model list with a broker-held key. Takes no caller-provided URL or key.
GET /v1/model-catalog	The model watcher	The models the broker has mapped.
POST /v1/task-certificates	The control plane only	Signs a task and workspace bound certificate for an active lease, valid until the lease expires. Registered only when a task CA is configured.

The broker accepts only identities it expects: the gateway certificate is spiffe://forelead/services/gateway, the watcher's is spiffe://forelead/services/model-watcher.

Control plane: MCP

POST /v1/mcp?workspaceId=... is a small, read-only JSON-RPC surface (MCP 2026-07-28) on the machine listener, for decision boards. It needs the workspace client certificate and a session bearer token, and refuses any method or tool outside its three.

Technical notes

• Broker configuration (BROKER_CONFIG) maps a model name to a URL and a key file. The key files stay outside agent workspaces and readable only by the broker.
• Anthropic credentials must be Console API keys. Claude subscription credentials are refused (#416).
• The task certificate and key stay outside the task container: a bridge in the job proxy sidecar holds them.

Sources

• cmd/gateway/main.go, cmd/broker/main.go, internal/server/mcp.go
• internal/modelgateway, internal/credentialbroker, internal/taskcert/http.go
• README.md ("Model gateway and credential broker"), api/internal-routes.yaml