InfernoFirewall exposes four API surfaces: the OpenAI-compatible runtime API for model calls, the MCP tool-call API, the control API for approvals, and the console JSON API for viewing and changing tenant state. They all use the same gateway API key, the same tenant model, and the same audit-first rule: consequential writes are recorded before they happen.
Authorization: Bearer <gateway-api-key> Content-Type: application/json
Every runtime, MCP, control and console API call authenticates with a gateway API key. Keys are tenant-scoped. Unknown keys return 401 without reaching the upstream provider.
| API | Authentication |
|---|---|
| Runtime, MCP, control, console | Authorization: Bearer <gateway-api-key> |
| Console roles | Cedar actions: console_view, console_manage, console_payload |
| Approvals | Cedar action approve_tool, evaluated against the exact arguments |
| Metrics listener | Optional bearer token when FW_METRICS_TOKEN is set |
The gateway stores provider credentials and injects them upstream. The caller's gateway key is not forwarded to providers.
Console access, model access, tool access and approval authority are Cedar decisions. No active bundle means no access.
Console payload reads write an audit record before the content is shown.
| Header | Purpose |
|---|---|
X-FW-Session | Set the firewall session. If omitted, the gateway derives one scoped to the caller. |
X-FW-Parent-Session | Attach a child agent to a parent session. The child inherits taint, scores and known targets; nothing flows back. |
x-fw-links-removed | Count of links removed from non-streaming output when hosts are not on the tenant allow-list. |
mcp-session-id | MCP transport session id. If X-FW-Session is absent, MCP calls group by this value. |
For real agents, send the same X-FW-Session on chat requests and MCP tool calls. That
keeps taint from a fetched page in the same session when the model proposes the next tool call.
| Endpoint | Usage |
|---|---|
GET /healthz | Liveness check. Returns ok. |
GET /readyz | Readiness check. Returns ready or 503 when the database is unavailable. |
GET /v1/models | OpenAI-compatible model list, filtered by the caller's policy. |
POST /v1/chat/completions | OpenAI-compatible chat completion. Supports streaming and non-streaming. |
curl -s http://localhost:8080/v1/models \
-H "Authorization: Bearer <gateway-api-key>"
curl -s http://localhost:8080/v1/chat/completions \
-H "Authorization: Bearer <gateway-api-key>" \
-H "X-FW-Session: demo-session" \
-H "content-type: application/json" \
-d '{
"model": "demo-fast",
"messages": [
{"role": "user", "content": "hello"}
]
}'
Stock OpenAI clients can point at the gateway. The gateway converts requests and responses into canonical events, then decides whether model access, tool calls, response content and outbound data are allowed.
Proposed tool calls are not executed. They are parsed, hashed, checked against tool schemas and Cedar policy, then released unchanged, redacted, held for approval, or denied.
Text chunks stream through. Tool-call deltas are held until the arguments JSON is complete.
Blocked actions return an OpenAI-shaped error or a refusal text that an agent can show to the user.
| Endpoint | Behavior |
|---|---|
POST /mcp | MCP Streamable HTTP endpoint. One JSON-RPC request per POST. |
GET /mcp | Returns 405. The gateway does not open a server-to-client stream. |
DELETE /mcp | Ends the MCP transport session. No firewall session is stored there. |
curl -s http://localhost:8080/mcp \
-H "Authorization: Bearer <gateway-api-key>" \
-H "X-FW-Session: demo-session" \
-H "content-type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {"name": "agent", "version": "1.0"}
}
}'
curl -s http://localhost:8080/mcp \
-H "Authorization: Bearer <gateway-api-key>" \
-H "X-FW-Session: demo-session" \
-H "content-type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}'
curl -s http://localhost:8080/mcp \
-H "Authorization: Bearer <gateway-api-key>" \
-H "X-FW-Session: demo-session" \
-H "content-type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "ws.read_file",
"arguments": {"path": "/workspace/note.txt"}
}
}'
MCP tool names are merged and namespaced, for example ws.read_file. A tool appears
only while its current description, schema and annotations match the approved pin. If the pin
changes upstream, the tool disappears until it is re-reviewed.
Every tool result is scanned, recorded, taints the session, and is delivered as untrusted origin data.
A denied or held call returns a JSON-RPC result with isError: true and the reason. Nothing reaches the upstream server.
Browser origins must be listed by the operator. Agents normally send no origin.
| Endpoint | Usage |
|---|---|
GET /v1/approvals?state=pending&limit=100 | List approvals visible to you: yours, plus approvals your policy lets you decide. |
GET /v1/approvals/{id} | Show one approval, including exact arguments and whether you can decide it. |
POST /v1/approvals/{id}/approve | Approve with optional {"note":"..."}. |
POST /v1/approvals/{id}/deny | Deny with optional {"note":"..."}. |
curl -s 'http://localhost:8080/v1/approvals?state=pending&limit=20' \
-H "Authorization: Bearer <approver-api-key>"
curl -s http://localhost:8080/v1/approvals/<approval-id>/approve \
-H "Authorization: Bearer <approver-api-key>" \
-H "content-type: application/json" \
-d '{"note":"approved for demo session"}'
Approval authority is a Cedar decision made from the tenant's active bundle. A caller cannot approve their own request, and an approval is tied to tenant, session, principal, tool pin and canonical arguments hash. If the tool pin or arguments change, the approval no longer applies.
The console is not just UI. It is a JSON API mounted at /console/api. Every response
is tenant-scoped, never cached, and every consequential change is audited first.
curl -s http://localhost:8080/console/api/me \ -H "Authorization: Bearer <gateway-api-key>" curl -s 'http://localhost:8080/console/api/decisions?limit=50' \ -H "Authorization: Bearer <viewer-api-key>" curl -s http://localhost:8080/console/api/shadow/report \ -H "Authorization: Bearer <viewer-api-key>"
| Area | Routes |
|---|---|
| Identity | GET /console/api/me |
| Decisions | GET /console/api/decisions, GET /console/api/decisions/{id}, GET /console/api/decisions/{id}/payload |
| Sessions | GET /console/api/sessions/{id} |
| Live feed | GET /console/api/live, WebSocket upgrade. Authenticate with the first message: {"auth":"<key>","filter":{}}. |
| Policies | GET|POST /console/api/policies, GET /console/api/policies/{hash}, POST /console/api/policies/{hash}/activate, validate, templates, render, explain, simulate, rollback |
| Tools | GET|POST /console/api/tools, POST /console/api/tools/status, GET /console/api/tools/history |
| Models | GET /console/api/models, POST /console/api/models/{id}/activate |
| Catalog | GET /console/api/catalog, provider save, credential set/clear, model save/status, trust, pricing, probe, routing, backends |
| Usage | GET /console/api/usage, GET /console/api/usage/rows, settings, keys, key tags |
| Exports | GET|POST /console/api/exports, PUT|DELETE /console/api/exports/{name}, secret set/clear, test |
| Health and mode | GET /console/api/health, GET|PUT /console/api/mode, GET /console/api/shadow/report |
| Metrics | GET /console/api/metrics |
Common filters: principal, kind, verdict, tool, model, rule, session, shadowed, since, before, limit.
Normal viewing does not imply payload viewing. Payload reads require console_payload and are recorded.
If the audit record cannot be committed, the console does not change tenant state.
| Endpoint | What it returns |
|---|---|
GET /healthz | Simple liveness response. |
GET /readyz | Database readiness. |
GET /metrics | Prometheus exposition, served on the separate listener when FW_METRICS_LISTEN is set. |
GET /console/api/metrics | Console metrics panel data, tenant-scoped. |
GET /console/api/health | Per-process counters plus database state: nodes, active bundle, active model, pending approvals and mode. |
export FW_METRICS_LISTEN=127.0.0.1:9090 export FW_METRICS_TOKEN=<optional-token> curl -s http://localhost:9090/metrics curl -s http://localhost:8080/console/api/health \ -H "Authorization: Bearer <viewer-api-key>"
Keep the Prometheus endpoint on its own listener. It has no tenant, principal or session labels, so it can be exposed for infrastructure monitoring without leaking tenant identity through labels.
| API | Error shape |
|---|---|
| Runtime API | OpenAI-shaped: error.message, error.type, error.code, error.param. |
| Control and console APIs | error.code and error.message. |
| MCP API | JSON-RPC error for transport/auth problems; tool decisions are returned as isError: true results. |
{
"error": {
"message": "Blocked by firewall (pii-then-sink): personal data was sent toward an external sink.",
"type": "firewall_error",
"code": "firewall_blocked",
"param": null
}
}
| Status | Common cases |
|---|---|
| 401 | Missing or invalid bearer API key. |
| 400 | Bad request, invalid JSON, invalid state, invalid cursor, invalid time. |
| 403 | Firewall block, role denial, origin not allowed, outbound data rule, approval denied. |
| 404 | Approval, decision, session, tool, model or export not visible to you. |
| 405 | GET /mcp, because the MCP stream is not implemented. |
| 502 | Upstream provider unavailable. |
| 503 | Firewall cannot verify or audit the request, so it fails closed. |
BASE=http://localhost:8080
KEY=<gateway-api-key>
SESSION=agent-session
curl -fs "$BASE/healthz"
curl -s "$BASE/v1/models" \
-H "Authorization: Bearer $KEY"
curl -s "$BASE/v1/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "X-FW-Session: $SESSION" \
-H "content-type: application/json" \
-d '{
"model": "demo-fast",
"messages": [{"role": "user", "content": "hello"}]
}'
curl -s "$BASE/v1/chat/completions" \
-H "Authorization: Bearer $KEY" \
-H "X-FW-Session: $SESSION" \
-H "content-type: application/json" \
-d '{
"model": "demo-fast",
"stream": true,
"messages": [{"role": "user", "content": "TOOL:read_file"}]
}'
curl -s "$BASE/v1/approvals?state=pending" \
-H "Authorization: Bearer $KEY"
curl -s "$BASE/console/api/decisions?limit=20" \
-H "Authorization: Bearer $KEY"
The same X-FW-Session is what connects a fetched page, a later tool proposal, session taint and budgets.
Non-streaming responses can rewrite unknown hosts and set x-fw-links-removed. Streamed text has already reached the client.
A denied or held tool call is not an exception to hide. It is a decision with a reason code, rule, session and audit record.
Approving one canonical argument hash does not approve a changed amount, changed recipient, changed tool pin or another session.