Saltar al contenido principal
El Agent Firewall se configura de dos formas: a través de la consola (tu sesión, el mismo login que usas para el dashboard) y a través del gateway (una clave API dedicada con alcance de firewall que tu agente presenta en tiempo de ejecución). Las dos familias viven en prefijos de ruta distintos, toman autenticación distinta y responden preguntas distintas — “editar la política” frente a “evaluar esta llamada a herramienta”. Esta página es el mapa ruta por ruta de ambas. Para saber qué significa la política — veredictos, superficies, reglas, resolución — empieza en Firewall y Reglas del firewall. Esta página es solo la superficie de la API.

​
1. Las dos familias de rutas

Consola — configurar

/api/workspace/firewall/*. Autenticado por tu token de sesión / acceso (UserAuth), acotado a tu espacio de trabajo activo. Autora políticas, lee eventos, registra servidores MCP, resuelve aprobaciones. Cada acción está gobernada por rol.

Gateway — aplicar

/api/v1/firewall/*. Autenticado por una clave con alcance de gateway de firewall (una clave con is_firewall_gateway establecido). La superficie máquina a máquina que tu agente o cliente MCP llama en tiempo de ejecución. Una clave de relay normal obtiene 403 aquí.
Las rutas de consola nunca toman una clave de relay sk-orca-…, y las rutas del gateway nunca toman un token de sesión. Confundirlas es el 401/403 más común al conectar el firewall por primera vez. La única clave sk-orca-… que pertenece en una llamada /v1/firewall/* es una acuñada con is_firewall_gateway activado — ve Alcance, claves y políticas.

​
2. Roles de un vistazo

Las rutas de consola resuelven tu rol de espacio de trabajo y gobiernan en consecuencia. Las lecturas que no llevan procedencia de llamada a herramienta están abiertas a cualquier miembro; las escrituras y cualquier cosa que exponga argumentos de llamada a herramienta requieren Developer+.
RolPuede hacer
Viewer / memberLeer configuración, políticas, presets, herramientas descubiertas, simulate, anomalías.
Developer+Todo lo anterior, más cada escritura, la superficie events/runs/trace y el dry-run test.
Admin+Adicionalmente, establecer el flag is_firewall_gateway en una clave y leer el texto plano de una clave de gateway.
La división es deliberada: un viewer puede ver que una política existe y qué bloquearía, pero no los argumentos de llamada a herramienta en bruto detrás de un evento. Si estás construyendo paneles para no desarrolladores, las rutas de lectura abierta son el conjunto seguro.

​
3. Configurar una política desde la consola

Las rutas de consola son cómo autoras e inspeccionas la política. Configuras todo en la UI del dashboard — estos son los mismos endpoints que llama.

​
Políticas y configuración

Método y rutaRolPropósito
GET /api/workspace/firewall/settingsMemberModo observe + conteos.
PUT /api/workspace/firewall/settingsDeveloper+Actualizar la configuración del firewall del espacio de trabajo.
GET /api/workspace/firewall/policiesMemberLista políticas.
GET /api/workspace/firewall/policies/:idMemberDetalle de una sola política.
POST /api/workspace/firewall/policiesDeveloper+Crear una política.
PUT /api/workspace/firewall/policiesDeveloper+Actualizar una política.
DELETE /api/workspace/firewall/policies/:idDeveloper+Eliminar una política.
POST /api/workspace/firewall/rulesDeveloper+Añadir una regla.
PUT /api/workspace/firewall/rulesDeveloper+Actualizar una regla.
DELETE /api/workspace/firewall/rules/:idDeveloper+Eliminar una regla.

​
Postura, presets y sandboxes

Método y rutaRolPropósito
GET /api/workspace/firewall/presetsMemberPresets de reglas integrados.
GET /api/workspace/firewall/templatesMemberGalería de plantillas por caso de uso.
POST /api/workspace/firewall/templates/applyDeveloper+Aplicar una plantilla → una política + sus reglas.
POST /api/workspace/firewall/autonomyDeveloper+Aplicar un nivel de autonomía (tight / balanced / permissive).
POST /api/workspace/firewall/autonomy/undo/:audit_idDeveloper+Deshacer de un clic desde el snapshot de auditoría.
GET /api/workspace/firewall/simulateMemberQué bloquearía un nivel (?level=).
POST /api/workspace/firewall/testDeveloper+Ejecutar en seco una política contra una llamada de muestra.

​
Observabilidad

Método y rutaRolPropósito
GET /api/workspace/firewall/discovered-toolsMemberHerramientas vistas, marcadas covered / gap.
GET /api/workspace/firewall/eventsDeveloper+Lista eventos del firewall (filtrable).
GET /api/workspace/firewall/events/by-request/:request_idDeveloper+Eventos de una solicitud.
GET /api/workspace/firewall/events/aggregateDeveloper+Agregado de ejecuciones / sesiones.
GET /api/workspace/firewall/trace/by-runDeveloper+Nodos de traza para una ejecución (?run_id=).
GET /api/workspace/firewall/anomaliesMemberFeed de anomalías.
POST /api/workspace/firewall/anomalies/snoozeDeveloper+Posponer el feed (≤ 7 días).

​
Servidores MCP

Registra los servidores Model Context Protocol que tus agentes alcanzan, detrás de un único gateway auditado. Las credenciales se almacenan cifradas y se enmascaran al leer.
Método y rutaRolPropósito
GET /api/workspace/firewall/mcp_serversMemberLista servidores registrados.
GET /api/workspace/firewall/mcp_servers/:idMemberDetalle del servidor.
POST /api/workspace/firewall/mcp_serversDeveloper+Registrar un servidor (409 ante un name duplicado).
PUT /api/workspace/firewall/mcp_serversDeveloper+Actualizar un servidor.
DELETE /api/workspace/firewall/mcp_servers/:idDeveloper+Eliminar un servidor.
POST /api/workspace/firewall/mcp_servers/:id/probeDeveloper+Handshake de alcanzabilidad + tools/list.
Un servidor lleva un name único, un endpoint, un auth_mode (none / bearer / oauth / basic) y un status de salud (ok / degraded / down). Ve Firewall MCP para el ciclo de vida completo y la cuarentena de skills.

​
4. Aplicar en el gateway

Estos se ejecutan sobre una clave con alcance de gateway de firewall, no tu sesión. Son lo que tu bucle de agente o cliente MCP llama en tiempo de ejecución.
Método y rutaPropósito
POST /api/v1/firewall/evaluateVeredicto previo al despacho para una llamada a herramienta.
POST /api/v1/firewall/evaluate_planVerificación previa a la ejecución para un plan de varios pasos.
ANY /api/v1/firewall/mcpEl endpoint unificado del gateway MCP.
GET /api/v1/firewall/mcp_serversEnumerar los servidores registrados del espacio de trabajo.
GET /api/v1/firewall/approvals/:idHacer polling del estado de aprobación de una llamada retenida.
POST /api/v1/firewall/approvals/:id/callbackCallback de aprobación firmado con HMAC.

​
Un ejemplo concreto: evaluar una llamada a herramienta

Antes de que tu agente despache una herramienta, pide al gateway un veredicto. Pasa la clave con alcance de gateway de firewall — no tu clave 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 /" }
  }'
La respuesta lleva el veredicto — allow, audit, deny, sanitize o pending_approval. Ante un deny omites la llamada y expones la razón al modelo; ante un sanitize reenvías los argumentos limpios que el gateway devuelve (sanitize redacta los argumentos de la llamada a herramienta solamente — nunca el contenido que una herramienta devuelve); ante un pending_approval entras en el bucle de aprobación de abajo.
El gateway evalúa las llamadas que lo cruzan — el hook evaluate, el gateway MCP y la ruta de relay. Una herramienta que tu agente ejecuta enteramente en proceso, sin tocar nunca OrcaRouter, está fuera de su vista. Enruta las llamadas que importan (herramientas mediadas por modelo, despacho MCP, egress de red) a través del gateway y quedan gobernadas.

​
5. El handshake de aprobación (HITL)

Un veredicto pending_approval retiene la llamada para un humano. El error HTTP mientras está retenida es firewall_approval_pending. Liberarla es un bucle de tres pasos repartido entre ambas familias de rutas:
1

Un revisor resuelve la retención

Desde la consola (PATCH /api/workspace/firewall/approvals/:id, Developer+), o tu propio sistema publica un callback firmado con HMAC a POST /api/v1/firewall/approvals/:id/callback. El callback verifica el HMAC en línea — no se acepta ninguna otra autenticación.
2

Tu agente hace polling de la aprobación

GET /api/v1/firewall/approvals/:id con la clave de gateway, hasta que el estado cambia a aprobado o rechazado.
3

Reenvía con el token de un solo uso

Una vez aprobado, reemite la llamada original llevando la cabecera X-OrcaRouter-Firewall-Approval con el id de aprobación. El gateway lo reconoce y deja pasar esa única llamada. La cabecera es de un solo uso.
Las decisiones son first-writer-wins e idempotentes — una segunda resolución de la misma retención es un no-op. Ve Firewall — Aprobación humana para el flujo de extremo a extremo y ¿Por qué se bloqueó esto? para leer un veredicto.

​
6. Cómo se ve un block

ResultadoHTTPCódigo
Llamada a herramienta denegada (superficie inbound)400firewall_blocked
Denegada vía gateway MCPerror de herramientafirewall deny: <reason>
Retenida para aprobación400firewall_approval_pending
firewall_blocked está marcado skip-retry — reejecutar la llamada idéntica simplemente volvería a bloquear, así que un cliente que reintenta hace backoff en vez de martillear. La lista completa de códigos vive en Códigos de error.

​
7. Referencias relacionadas

API de Guardrail

El par de política de contenido — rutas /api/guardrail/* para el plano de texto.

Glosario de veredictos

Cada veredicto y lo que le hace a una llamada.

Glob y JSONPath

La gramática de coincidencia detrás de tool_name_glob y args_match.

API de Compliance

Packs, reportes firmados, residencia y borrado.

​
8. FAQ

Las rutas del gateway requieren una clave con alcance de gateway de firewall — una acuñada con is_firewall_gateway establecido (una acción Admin+). Una clave de relay normal, incluso válida, obtiene 403. Acuña una clave de gateway dedicada para el runtime de tu agente.
No. Las rutas events, events/aggregate y trace son Developer+ porque los registros llevan procedencia de argumentos de llamada a herramienta. Los viewers pueden leer configuración, políticas, presets, herramientas descubiertas, simulate y el feed de anomalías.
Cualquiera. Un humano la resuelve en la consola vía PATCH /api/workspace/firewall/approvals/:id (Developer+), o tu propio sistema publica una decisión firmada con HMAC a POST /api/v1/firewall/approvals/:id/callback. El agente hace polling de GET /api/v1/firewall/approvals/:id sin importar qué ruta la resolvió.
No. Un veredicto sanitize redacta los argumentos de la llamada a herramienta solamente — nunca el contenido que una herramienta devuelve. En la superficie inbound, donde aún no hay argumentos en tiempo de llamada, sanitize escala a un bloqueo. Ve Reglas del firewall.
Para saber cómo se componen estos controles con los guardrails y el resto del gateway, ve Asegurar agentes de IA y Guardrails vs Firewall.