1. Los tres alcances
Tres conceptos se anidan entre sí:- Espacio de trabajo — el límite del tenant. Cada miembro de un espacio de trabajo comparte el mismo catálogo de guardrails y políticas de firewall. Nada cruza los límites del espacio de trabajo — una política creada en el espacio de trabajo A es invisible para el espacio de trabajo B.
- Política — un conjunto de reglas nombrado, con alcance de espacio de trabajo (guardrail o política de firewall). Editar una política surte efecto en cada clave adjunta a ella en la siguiente solicitud, sin redespliegue.
- Clave — identidad más adjuntos. Una clave lleva sus propias restricciones y apunta a las políticas que la gobiernan.
2. Lo que lleva una clave
Cada clave API es un paquete de límites y adjuntos. Establécelos en el editor de claves (/console/token) — crear o editar claves requiere el rol
Developer o superior.
| Campo | Qué limita | Rol mínimo para establecer |
|---|---|---|
model_limits | Restringe la clave a una lista específica de modelos — cualquier llamada fuera de esa lista se rechaza antes de salir del gateway. | Developer |
allow_ips | Lista de IPs permitidas. Las solicitudes desde cualquier dirección no listada se rechazan en la capa de autenticación. Vacío significa que todas las IPs están permitidas. | Developer |
credit_limit_usd | Tope de gasto en USD. 0 significa ilimitado. El gateway aplica esto contra el gasto de por vida de la clave. | Developer |
expired_time | Marca de tiempo de expiración absoluta. -1 significa que la clave nunca expira. | Developer |
environment | Una etiqueta de texto libre (p. ej. prod, staging, dev) para organizar claves y filtrar logs. | Developer |
guardrail_id | Adjunta un guardrail específico a esta clave. Cada llamada que hace esta clave es examinada por ese guardrail. | Developer |
firewall_policy_id | Adjunta una política de firewall específica a esta clave. Cada llamada a herramienta que emite esta clave es evaluada por esa política. | Developer |
is_firewall_gateway | Marca la clave como un token con alcance de gateway — requerido para llamar a las rutas de despacho MCP y hook de evaluación. Una clave normal obtiene 403 en esas rutas. Leer el texto plano de una clave de gateway requiere Admin. | Admin (para habilitar y leer texto plano) |
3. Orden de resolución de políticas
Para cualquier solicitud, OrcaRouter resuelve el guardrail activo y la política de firewall independientemente:- Adjunto a la clave — si la clave tiene un
guardrail_idexplícito (ofirewall_policy_id) y esa política existe y está habilitada, aplica. - Valor por defecto del espacio de trabajo — si la clave no tiene adjunto,
el guardrail (o política) habilitado
is_defaultdel espacio de trabajo aplica. - Sin aplicación — si ninguno está establecido, la solicitud pasa sin examen de contenido ni aplicación de llamadas a herramienta.
Los dos planos difieren cuando una política adjunta está deshabilitada:
- Un adjunto de guardrail deshabilitado o eliminado significa que la clave no obtiene ningún guardrail — deshabilitarlo es el interruptor de apagado; no hace fallback al valor por defecto del espacio de trabajo.
- Un adjunto de firewall deshabilitado hace fallback a la política de firewall por defecto del espacio de trabajo — así que deshabilitar un adjunto de firewall revierte la clave al valor por defecto del espacio de trabajo, no desactiva la aplicación.
0/no establecido) siempre hace fallback al valor por
defecto del espacio de trabajo; ninguno de los dos establecido significa sin
aplicación.4. Claves de mínima agencia — una clave por agente
La configuración más segura es dar a cada agente su propia clave con alcance estrecho en lugar de compartir una sola clave del espacio de trabajo entre todos los llamadores. Una clave bien acotada para un agente que solo llama a un modelo y ejecuta tareas programadas podría verse así:model_limits:["openai/gpt-4o-mini"]— el agente no puede cambiar a un modelo más caro o más capaz.allow_ips: el CIDR de egress del programador — ninguna otra fuente puede presentar esta clave.credit_limit_usd: un techo de presupuesto semanal — un bucle descontrolado no puede agotar el saldo de tu espacio de trabajo.expired_time: el final del sprint o ciclo de vida del despliegue — la clave expira automáticamente y no puede reutilizarse.guardrail_id: un guardrail específico para la sensibilidad de datos de este agente — más estricto que el valor por defecto del espacio de trabajo.firewall_policy_id: una política que permite solo las herramientas que este agente legítimamente necesita.
Crea claves con alcance de gateway (
is_firewall_gateway) solo para la
superficie de despacho MCP o hook de evaluación — nunca para tráfico de
inferencia general. Una clave de gateway en la ruta de inferencia da al
llamador acceso a las rutas /api/v1/firewall/*, que es una capacidad más
amplia de la que necesita. Una clave, un propósito.5. Dónde se crean las políticas
Los guardrails y las políticas de firewall tienen ambos alcance de espacio de trabajo y se comparten entre todos los miembros, pero los cambios requieren el rol correcto:- Leer cualquier guardrail, política o clave — cualquier miembro del espacio de trabajo.
- Crear o cambiar guardrails, políticas de firewall, servidores MCP, niveles de autonomía, acciones de aprobación y claves API ordinarias — Developer+.
- Habilitar
is_firewall_gatewayen una clave; leer el texto plano de una clave de gateway — Admin+.
6. Próximos pasos
Línea base de Agentes Seguros
La postura de inicio recomendada — un interruptor de nivel de autonomía,
luego ajusta desde el tráfico real.
Obtener una clave API
Crea tu primera clave y adjunta un guardrail o política de firewall en la
consola.