Referência da API de Firewall

O Agent Firewall é configurado de duas maneiras: através do console (sua sessão, o mesmo login que você usa para o dashboard) e através do gateway (uma chave de API dedicada com escopo de firewall que seu agente apresenta em tempo de execução). As duas famílias vivem em prefixos de path diferentes, tomam autenticação diferente e respondem a perguntas diferentes — “edite a política” versus “avalie esta chamada de ferramenta”. Esta página é o mapa rota a rota de ambas. Para o que a política significa — vereditos, superfícies, regras, resolução — comece em Firewall e Regras de firewall. Esta página é apenas a superfície da API.

1. As duas famílias de rotas

Console — configurar

/api/workspace/firewall/*. Autenticado pelo seu token de sessão / acesso (UserAuth), com escopo para o seu workspace ativo. Crie políticas, leia eventos, registre servidores MCP, resolva aprovações. Toda ação é controlada por papel.

Gateway — aplicar

/api/v1/firewall/*. Autenticado por uma chave com escopo de firewall-gateway (uma chave com is_firewall_gateway definido). A superfície machine-to-machine que seu agente ou cliente MCP chama em tempo de execução. Uma chave de relay normal recebe 403 aqui.

As rotas de console nunca tomam uma chave de relay sk-orca-…, e as rotas de gateway nunca tomam um token de sessão. Confundi-las é o 401/403 mais comum ao conectar o firewall pela primeira vez. A única chave sk-orca-… que pertence a uma chamada /v1/firewall/* é uma cunhada com is_firewall_gateway ligado — veja Escopo, chaves & políticas.

2. Papéis em resumo

As rotas de console resolvem seu papel de workspace e controlam de acordo. Leituras que não carregam proveniência de chamada de ferramenta são abertas a qualquer membro; escritas e qualquer coisa que exponha argumentos de chamada de ferramenta exigem Developer+.

Papel	Pode fazer
Viewer / membro	Ler settings, políticas, presets, ferramentas descobertas, simulate, anomalias.
Developer+	Tudo acima, mais cada escrita, a superfície `events`/`runs`/`trace` e o dry-run `test`.
Admin+	Adicionalmente, definir a flag `is_firewall_gateway` em uma chave e ler o texto em claro de uma chave de gateway.

A divisão é deliberada: um viewer pode ver que uma política existe e o que ela bloquearia, mas não os argumentos brutos da chamada de ferramenta por trás de um evento. Se você está construindo dashboards para não-desenvolvedores, as rotas abertas para leitura são o conjunto seguro.

3. Configure uma política a partir do console

As rotas de console são como você cria e inspeciona a política. Você configura tudo na UI do dashboard — estes são os mesmos endpoints que ela chama.

Políticas & settings

Método & path	Papel	Propósito
`GET /api/workspace/firewall/settings`	Member	Observe-mode + contagens.
`PUT /api/workspace/firewall/settings`	Developer+	Atualiza configurações de firewall do workspace.
`GET /api/workspace/firewall/policies`	Member	Lista políticas.
`GET /api/workspace/firewall/policies/:id`	Member	Detalhe de uma única política.
`POST /api/workspace/firewall/policies`	Developer+	Cria uma política.
`PUT /api/workspace/firewall/policies`	Developer+	Atualiza uma política.
`DELETE /api/workspace/firewall/policies/:id`	Developer+	Deleta uma política.
`POST /api/workspace/firewall/rules`	Developer+	Adiciona uma regra.
`PUT /api/workspace/firewall/rules`	Developer+	Atualiza uma regra.
`DELETE /api/workspace/firewall/rules/:id`	Developer+	Deleta uma regra.

Postura, presets & sandboxes

Método & path	Papel	Propósito
`GET /api/workspace/firewall/presets`	Member	Presets de regra embutidos.
`GET /api/workspace/firewall/templates`	Member	Galeria de templates por caso de uso.
`POST /api/workspace/firewall/templates/apply`	Developer+	Aplica um template → uma política + suas regras.
`POST /api/workspace/firewall/autonomy`	Developer+	Aplica um nível de autonomia (`tight` / `balanced` / `permissive`).
`POST /api/workspace/firewall/autonomy/undo/:audit_id`	Developer+	Desfazer em um clique a partir do snapshot de auditoria.
`GET /api/workspace/firewall/simulate`	Member	O que um nível bloquearia (`?level=`).
`POST /api/workspace/firewall/test`	Developer+	Dry-run de uma política contra uma chamada de amostra.

Observabilidade

Método & path	Papel	Propósito
`GET /api/workspace/firewall/discovered-tools`	Member	Ferramentas vistas, marcadas covered / gap.
`GET /api/workspace/firewall/events`	Developer+	Lista eventos de firewall (filtrável).
`GET /api/workspace/firewall/events/by-request/:request_id`	Developer+	Eventos de uma requisição.
`GET /api/workspace/firewall/events/aggregate`	Developer+	Rollup de runs / sessions.
`GET /api/workspace/firewall/trace/by-run`	Developer+	Nós de trace de uma run (`?run_id=`).
`GET /api/workspace/firewall/anomalies`	Member	Feed de anomalias.
`POST /api/workspace/firewall/anomalies/snooze`	Developer+	Dá snooze no feed (≤ 7 dias).

Servidores MCP

Registre os servidores Model Context Protocol que seus agentes alcançam, atrás de um único gateway auditado. As credenciais são armazenadas criptografadas e mascaradas na leitura.

Método & path	Papel	Propósito
`GET /api/workspace/firewall/mcp_servers`	Member	Lista servidores registrados.
`GET /api/workspace/firewall/mcp_servers/:id`	Member	Detalhe do servidor.
`POST /api/workspace/firewall/mcp_servers`	Developer+	Registra um servidor (`409` em um `name` duplicado).
`PUT /api/workspace/firewall/mcp_servers`	Developer+	Atualiza um servidor.
`DELETE /api/workspace/firewall/mcp_servers/:id`	Developer+	Remove um servidor.
`POST /api/workspace/firewall/mcp_servers/:id/probe`	Developer+	Handshake de alcançabilidade + `tools/list`.

Um servidor carrega um name único, um endpoint, um auth_mode (none / bearer / oauth / basic) e um status de saúde (ok / degraded / down). Veja Firewall MCP para o ciclo de vida completo e a quarentena de skills.

4. Aplique no gateway

Estas rodam em uma chave com escopo de firewall-gateway, não na sua sessão. São o que seu loop de agente ou cliente MCP chama em tempo de execução.

Método & path	Propósito
`POST /api/v1/firewall/evaluate`	Veredito pré-dispatch para uma chamada de ferramenta.
`POST /api/v1/firewall/evaluate_plan`	Verificação pré-execução para um plano de múltiplos passos.
`ANY /api/v1/firewall/mcp`	O endpoint unificado do gateway MCP.
`GET /api/v1/firewall/mcp_servers`	Enumera os servidores registrados do workspace.
`GET /api/v1/firewall/approvals/:id`	Consulta o estado de aprovação de uma chamada retida.
`POST /api/v1/firewall/approvals/:id/callback`	Callback de aprovação assinado por HMAC.

Um exemplo concreto: avaliar uma chamada de ferramenta

Antes de o seu agente despachar uma ferramenta, peça um veredito ao gateway. Passe a chave com escopo de firewall-gateway — não sua chave de relay sk-orca-…:

curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer <firewall-gateway-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" }
  }'

A resposta carrega o veredito — allow, audit, deny, sanitize ou pending_approval. Em deny você pula a chamada e expõe o motivo ao modelo; em sanitize você encaminha os argumentos limpos que o gateway devolve (sanitize redige apenas os argumentos da chamada de ferramenta — nunca o conteúdo que uma ferramenta retorna); em pending_approval você entra no loop de aprovação abaixo.

O gateway avalia as chamadas que o cruzam — o hook evaluate, o gateway MCP e o caminho de relay. Uma ferramenta que seu agente roda inteiramente em-processo, nunca tocando o OrcaRouter, está fora da sua visão. Roteie as chamadas que importam (ferramentas mediadas por modelo, dispatch de MCP, egress de rede) através do gateway e elas estão governadas.

5. O handshake de aprovação (HITL)

Um veredito pending_approval retém a chamada para um humano. O erro HTTP enquanto retida é firewall_approval_pending. Liberá-la é um loop de três passos dividido entre ambas as famílias de rotas:

Um revisor resolve o hold

A partir do console (PATCH /api/workspace/firewall/approvals/:id, Developer+), ou seu próprio sistema posta um callback assinado por HMAC para POST /api/v1/firewall/approvals/:id/callback. O callback verifica o HMAC inline — nenhuma outra autenticação é aceita.

Seu agente consulta a aprovação

GET /api/v1/firewall/approvals/:id com a chave de gateway, até o estado virar aprovado ou rejeitado.

Reenvie com o token de uso único

Uma vez aprovada, reemita a chamada original carregando o header X-OrcaRouter-Firewall-Approval com o id de aprovação. O gateway o reconhece e deixa aquela única chamada passar. O header é de uso único.

As decisões são first-writer-wins e idempotentes — uma segunda resolução do mesmo hold é um no-op. Veja Firewall — Aprovação humana para o fluxo de ponta a ponta e Por que isto foi bloqueado? para ler um veredito.

6. Como é um bloqueio

Resultado	HTTP	Código
Chamada de ferramenta negada (superfície inbound)	`400`	`firewall_blocked`
Negada via gateway MCP	erro de ferramenta	`firewall deny: <reason>`
Retida para aprovação	`400`	`firewall_approval_pending`

firewall_blocked é marcado skip-retry — reexecutar a chamada idêntica apenas bloquearia de novo, então um cliente com retry recua em vez de martelar. A lista completa de códigos vive em Códigos de erro.

7. Referências relacionadas

API de Guardrail

O par de política de conteúdo — rotas /api/guardrail/* para o plano de texto.

Glossário de vereditos

Cada veredito e o que ele faz com uma chamada.

Glob & JSONPath

A gramática de correspondência por trás de tool_name_glob e args_match.

API de Compliance

Packs, relatórios assinados, residência e erasure.

8. FAQ

Por que minha chave de relay recebe um 403 em /api/v1/firewall/evaluate?

As rotas do gateway exigem uma chave com escopo de firewall-gateway — uma cunhada com is_firewall_gateway definido (uma ação de Admin+). Uma chave de relay normal, mesmo que válida, recebe 403. Cunhe uma chave de gateway dedicada para o runtime do seu agente.

Um viewer pode ler eventos de firewall?

Não. As rotas events, events/aggregate e trace são Developer+ porque os registros carregam proveniência de argumentos de chamada de ferramenta. Viewers podem ler settings, políticas, presets, ferramentas descobertas, simulate e o feed de anomalias.

Onde resolvo uma aprovação retida — console ou gateway?

Qualquer um. Um humano a resolve no console via PATCH /api/workspace/firewall/approvals/:id (Developer+), ou seu próprio sistema posta uma decisão assinada por HMAC para POST /api/v1/firewall/approvals/:id/callback. O agente consulta GET /api/v1/firewall/approvals/:id independentemente de qual caminho a resolveu.

O sanitize limpa o que uma ferramenta retorna?

Não. Um veredito sanitize redige apenas os argumentos da chamada de ferramenta — nunca o conteúdo que uma ferramenta retorna. Na superfície inbound, onde ainda não há argumentos em tempo de chamada, o sanitize escala para um bloqueio. Veja Regras de firewall.

Para como esses controles se compõem com os guardrails e o resto do gateway, veja Segurança de agentes de IA e Guardrails vs Firewall.

​1. As duas famílias de rotas

Console — configurar

Gateway — aplicar

​2. Papéis em resumo

​3. Configure uma política a partir do console

​Políticas & settings

​Postura, presets & sandboxes

​Observabilidade

​Servidores MCP

​4. Aplique no gateway

​Um exemplo concreto: avaliar uma chamada de ferramenta

​5. O handshake de aprovação (HITL)

​6. Como é um bloqueio

​7. Referências relacionadas

API de Guardrail

Glossário de vereditos

Glob & JSONPath

API de Compliance

​8. FAQ

1. As duas famílias de rotas

2. Papéis em resumo

3. Configure uma política a partir do console

Políticas & settings

Postura, presets & sandboxes

Observabilidade

Servidores MCP

4. Aplique no gateway

Um exemplo concreto: avaliar uma chamada de ferramenta

5. O handshake de aprovação (HITL)

6. Como é um bloqueio

7. Referências relacionadas

8. FAQ