Saltar al contenido principal
Para ejecutar llamadas a herramienta a través del agent firewall desde fuera del relay de modelo — tu propio bucle de agente llamando al hook evaluate, o un cliente MCP conectándose al gateway MCP — te autenticas con una clave dedicada con alcance de gateway de firewall, no una clave de relay sk-orca-… ordinaria. Una clave normal obtiene 403 en las rutas de gateway de firewall autenticadas por token (el callback de aprobación es la única excepción — está firmado con HMAC, no gobernado por token). Esta página cubre qué es una clave API de gateway de firewall, cómo acuñar una, y por qué el alcance está gobernado a Admin+. Para el motor en sí, ver la Visión general del Firewall y la referencia profunda en Firewall.

​
1. Qué es una clave API de gateway de firewall

Cada token (clave API) en tu espacio de trabajo lleva un flag is_firewall_gateway. Cuando es true, la clave puede alcanzar la superficie de gateway de firewall:
RutaQué hace
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_serversEnumera los servidores MCP registrados del espacio de trabajo (devuelve la auth upstream descifrada).
GET /api/v1/firewall/approvals/:idHace polling del estado de aprobación de una llamada retenida.
Una clave con is_firewall_gateway = false (el valor por defecto) es una clave de relay normal — atiende tráfico de modelo /v1/* y, si has adjuntado una política vía firewall_policy_id, sus llamadas a herramienta se gobiernan en línea. Pero no puede llamar a las rutas de gateway de arriba.
Dos claves diferentes, dos trabajos diferentes. Tu clave de relay (con firewall_policy_id adjunto) es lo que tu agente usa para hablar con los modelos — el firewall gobierna sus llamadas a herramienta automáticamente. Una clave de gateway de firewall es lo que el runtime de tu agente usa para pedirle al firewall un veredicto directamente, o para hacer proxy de tools/call MCP a través del gateway. La mayoría de los espacios de trabajo solo necesitan una clave de gateway una vez que adoptan el hook de evaluación o el gateway MCP.

​
2. Por qué una clave normal obtiene 403

El alcance de gateway desbloquea dos capacidades sensibles a secretos, así que está deliberadamente amurallado de las claves ordinarias:
  • /evaluate acepta un request_id suministrado por el llamador que fluye hacia el evento del firewall y los registros de aprobación. Que cualquier clave de modelo pudiera falsificar eventos de auditoría o sondear silenciosamente los resultados de política socavaría el rastro.
  • /mcp_servers devuelve credenciales upstream descifradas para que el proxy del SDK pueda despachar a tus servidores MCP registrados. Esa es una lectura de credenciales, no una llamada a modelo.
Por esto, el manejador verifica el flag is_firewall_gateway del token presentado y devuelve HTTP 403 cuando está ausente: 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
No reutilices una clave de relay de alto tráfico como clave de gateway, y no reutilices una clave de gateway para tráfico de relay. Mantén la clave del plano de acción separada para que su radio de explosión y su rotación sean independientes de tus claves de modelo.

​
3. Acuña una — gobernada por rol a Admin+

Establecer is_firewall_gateway = true requiere Admin del espacio de trabajo o superior. Un Developer puede crear y editar claves ordinarias, pero no puede acuñar una con alcance de gateway — el flag es un asunto de gestión de secretos, así que se sitúa por encima del rol normal de escritura de tokens. Configuras las claves en la consola, bajo las claves API de tu espacio de trabajo. Para acuñar una clave de gateway:
1

Abre las claves API como Admin

Inicia sesión como Admin del espacio de trabajo (o superior) y abre la página de claves API en la consola.
2

Crea una clave con el alcance de gateway

Crea una clave nueva y habilita su alcance de firewall gateway (is_firewall_gateway). Una sesión de rol Developer no verá el alcance surtir efecto — el servidor mantiene el flag en false para no-admins.
3

Copia la clave una vez

Copia el valor completo de la clave al crearla. Después la consola la enmascara en pantalla, y leer de vuelta el texto plano de una clave de gateway es en sí mismo Admin+ — los no-admins obtienen las filas de gateway omitidas de una respuesta de “obtener mis claves”.
Bajar el flag es más permisivo que subirlo: limpiar is_firewall_gateway (degradar una clave de gateway de vuelta a una clave normal) está abierto a cualquier rol que pueda editar la clave. Solo subirlo a true es Admin+.

​
Compuertas de rol de un vistazo

AcciónRol
Crear/editar una clave ordinariaDeveloper+
Establecer is_firewall_gateway = trueAdmin+
Leer de vuelta el texto plano de una clave de gatewayAdmin+
Limpiar is_firewall_gateway (degradar)cualquier editor de claves

​
4. Un ejemplo concreto

Estás ejecutando un bucle de agente y quieres verificar una llamada a herramienta antes de despacharla. Como Admin, acuña una clave de gateway en la consola, luego llama al hook de evaluación desde tu runtime con esa clave: 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer sk-orca-GATEWAY-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" },
    "request_id": "run-42-step-3"
  }'
El firewall resuelve la política activa de tu espacio de trabajo y devuelve el veredicto — allow, audit, deny, sanitize, pending_approval o una resolución cap_cost. Tu agente actúa sobre él: despachar en allow, omitir en deny, hacer polling del id de aprobación en pending_approval. La misma clave de gateway autentica las rutas de polling de aprobación y MCP.
¿Apuntando un cliente MCP (Claude Desktop, Cursor, un framework de agentes) a https://api.orcarouter.ai/api/v1/firewall/mcp? Usa la clave de gateway como su token bearer. Cada tools/call se evalúa entonces en la superficie mcp antes de reenviarse upstream.

​
5. Dónde encaja

Una clave de gateway autentica las rutas de gateway. No reemplaza la sesión de consola que usas para autorar política: crear políticas, editar reglas, registrar servidores MCP y resolver aprobaciones se ejecutan todos bajo tu propia sesión en /api/workspace/firewall/* (las lecturas de configuración, política y herramientas descubiertas abiertas a cada miembro; el sandbox de test de ejecución en seco y todas las escrituras requieren Developer+). La clave de gateway solo lleva solicitudes de veredicto y despacho MCP desde tu runtime de máquina a máquina.

Alcance: claves, políticas, espacios de trabajo

Cómo el firewall_policy_id de una clave y un alcance de gateway se relacionan con la frontera del espacio de trabajo.

Aprobaciones

El flujo de llamada retenida que tu clave de gateway hace polling y reenvía.

Webhook de aprobación

El callback firmado con HMAC que resuelve una llamada retenida fuera de banda.

Servidores MCP

Registra y gobierna servidores MCP detrás del endpoint del gateway.

​
6. FAQ

Subir is_firewall_gateway a true es Admin+. Una escritura de rol Developer que establece el flag se mantiene silenciosamente en false (para que un renombrado o edición de cuota no relacionados en la misma solicitud aún tengan éxito) — la clave simplemente no llevará el alcance. Recréala o edítala como Admin.
La clave presentada no tiene alcance de gateway. Confirma que fue acuñada con is_firewall_gateway = true por un Admin — una clave de relay normal siempre obtiene 403 en estas rutas. Ver §2.
Técnicamente una clave con alcance de gateway también puede atender tráfico de relay /v1/*, pero mantenlas separadas: una clave de relay (con firewall_policy_id adjunto) para modelos, una clave de gateway para las rutas de evaluate/MCP/aprobación. Rotación independiente, menor radio de explosión.
Las claves se enmascaran después de la creación, y leer el texto plano de una clave de gateway es Admin+. Si no la copiaste en tiempo de acuñación, crea una clave de gateway nueva y retira la antigua.