API Reference & Usage Guide

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.

Authentication

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.

APIAuthentication
Runtime, MCP, control, consoleAuthorization: Bearer <gateway-api-key>
Console rolesCedar actions: console_view, console_manage, console_payload
ApprovalsCedar action approve_tool, evaluated against the exact arguments
Metrics listenerOptional bearer token when FW_METRICS_TOKEN is set

Provider keys stay server-side

The gateway stores provider credentials and injects them upstream. The caller's gateway key is not forwarded to providers.

Roles are policy decisions

Console access, model access, tool access and approval authority are Cedar decisions. No active bundle means no access.

Reads can be recorded too

Console payload reads write an audit record before the content is shown.

Session headers

HeaderPurpose
X-FW-SessionSet the firewall session. If omitted, the gateway derives one scoped to the caller.
X-FW-Parent-SessionAttach a child agent to a parent session. The child inherits taint, scores and known targets; nothing flows back.
x-fw-links-removedCount of links removed from non-streaming output when hosts are not on the tenant allow-list.
mcp-session-idMCP 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.

Runtime API

EndpointUsage
GET /healthzLiveness check. Returns ok.
GET /readyzReadiness check. Returns ready or 503 when the database is unavailable.
GET /v1/modelsOpenAI-compatible model list, filtered by the caller's policy.
POST /v1/chat/completionsOpenAI-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.

Tool calls are decisions

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.

Streaming is supported

Text chunks stream through. Tool-call deltas are held until the arguments JSON is complete.

Denials are client-readable

Blocked actions return an OpenAI-shaped error or a refusal text that an agent can show to the user.

MCP API

EndpointBehavior
POST /mcpMCP Streamable HTTP endpoint. One JSON-RPC request per POST.
GET /mcpReturns 405. The gateway does not open a server-to-client stream.
DELETE /mcpEnds 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.

Tool results are recorded before the model sees them

Every tool result is scanned, recorded, taints the session, and is delivered as untrusted origin data.

Refusals become tool errors

A denied or held call returns a JSON-RPC result with isError: true and the reason. Nothing reaches the upstream server.

Origins are checked

Browser origins must be listed by the operator. Agents normally send no origin.

Control API

EndpointUsage
GET /v1/approvals?state=pending&limit=100List 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}/approveApprove with optional {"note":"..."}.
POST /v1/approvals/{id}/denyDeny 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.

Console JSON API

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>"
AreaRoutes
IdentityGET /console/api/me
DecisionsGET /console/api/decisions, GET /console/api/decisions/{id}, GET /console/api/decisions/{id}/payload
SessionsGET /console/api/sessions/{id}
Live feedGET /console/api/live, WebSocket upgrade. Authenticate with the first message: {"auth":"<key>","filter":{}}.
PoliciesGET|POST /console/api/policies, GET /console/api/policies/{hash}, POST /console/api/policies/{hash}/activate, validate, templates, render, explain, simulate, rollback
ToolsGET|POST /console/api/tools, POST /console/api/tools/status, GET /console/api/tools/history
ModelsGET /console/api/models, POST /console/api/models/{id}/activate
CatalogGET /console/api/catalog, provider save, credential set/clear, model save/status, trust, pricing, probe, routing, backends
UsageGET /console/api/usage, GET /console/api/usage/rows, settings, keys, key tags
ExportsGET|POST /console/api/exports, PUT|DELETE /console/api/exports/{name}, secret set/clear, test
Health and modeGET /console/api/health, GET|PUT /console/api/mode, GET /console/api/shadow/report
MetricsGET /console/api/metrics

Decision search

Common filters: principal, kind, verdict, tool, model, rule, session, shadowed, since, before, limit.

Payload access is separate

Normal viewing does not imply payload viewing. Payload reads require console_payload and are recorded.

Console writes are audited first

If the audit record cannot be committed, the console does not change tenant state.

Observability API

EndpointWhat it returns
GET /healthzSimple liveness response.
GET /readyzDatabase readiness.
GET /metricsPrometheus exposition, served on the separate listener when FW_METRICS_LISTEN is set.
GET /console/api/metricsConsole metrics panel data, tenant-scoped.
GET /console/api/healthPer-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.

Error shape and status codes

APIError shape
Runtime APIOpenAI-shaped: error.message, error.type, error.code, error.param.
Control and console APIserror.code and error.message.
MCP APIJSON-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
  }
}
StatusCommon cases
401Missing or invalid bearer API key.
400Bad request, invalid JSON, invalid state, invalid cursor, invalid time.
403Firewall block, role denial, origin not allowed, outbound data rule, approval denied.
404Approval, decision, session, tool, model or export not visible to you.
405GET /mcp, because the MCP stream is not implemented.
502Upstream provider unavailable.
503Firewall cannot verify or audit the request, so it fails closed.

Practical usage guide

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"

Use one session across chat and MCP

The same X-FW-Session is what connects a fetched page, a later tool proposal, session taint and budgets.

Use non-streaming when link stripping matters

Non-streaming responses can rewrite unknown hosts and set x-fw-links-removed. Streamed text has already reached the client.

Treat denied tool calls as events

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.

Approvals are single-use and exact

Approving one canonical argument hash does not approve a changed amount, changed recipient, changed tool pin or another session.