1. Por qué claves api con alcance para agentes llm
Una clave API general es una credencial al portador: quien la posea puede llamar a cualquier modelo, desde cualquier lugar, por cualquier monto, sin política adjunta. Eso es lo opuesto a lo que necesita un agente autónomo. En OrcaRouter, una clave API no es solo una credencial — es una declaración de alcance. Cada clave lleva sus propias restricciones (qué modelos, qué IPs, cuánto gasto, cuándo expira) y apunta a la guardrail y la política de firewall que gobiernan su tráfico. Editar la política a la que apunta una clave surte efecto en la siguiente solicitud, sin redespliegue y sin cambio de código del agente. El principio es mínima agencia: da a cada agente la identidad más estrecha que aún le permita hacer su trabajo, y nada más. Una clave, un agente, un propósito.2. Qué lleva una clave con alcance
Cada clave es un paquete de límites más dos adjuntos de política. Cada campo está documentado en su propia página — los enlaces radiales de abajo van a la profundidad.Límites de modelo
model_limits restringe una clave a una lista nombrada de modelos. Una
llamada fuera de la lista se rechaza antes de que salga del gateway — el
agente no puede cambiar a un modelo más caro o más capaz.Lista de IPs permitidas
allow_ips fija una clave a direcciones de origen específicas. Una clave
filtrada presentada desde cualquier otro lugar se rechaza en la capa de
autenticación.Cuota, tope y expiración
credit_limit_usd topa el gasto de por vida (0 = ilimitado);
expired_time establece una expiración absoluta (-1 = nunca).Entornos
environment es una etiqueta de forma libre (prod, staging, dev)
para organizar claves y filtrar logs.Vincular políticas
guardrail_id y firewall_policy_id adjuntan una política de contenido y
una política de llamadas a herramienta a la clave. Sin adjunto se hace
fallback al valor por defecto del espacio de trabajo.El objeto token
La referencia campo por campo completa de una clave, incluyendo
remain_quota / used_quota e is_firewall_gateway.Acotada vs sin acotar. Una clave con
credit_limit_usd: 0 y
expired_time: -1 no tiene tope de gasto y nunca expira — conveniente, pero
el peor radio de explosión si se filtra. Ver
ilimitada vs acotada para cuándo es
apropiada cada una.3. Una clave de mínima agencia concreta
Un agente programado que resume tickets de soporte con un modelo barato y se ejecuta desde un host necesita casi ninguna agencia. Una clave bien acotada para él:| Campo | Valor | Por qué |
|---|---|---|
model_limits | un modelo de resumen | no puede escalar a un modelo frontera |
allow_ips | el CIDR de egress del programador | una clave filtrada es inútil en otro lugar |
credit_limit_usd | un techo semanal | un bucle descontrolado no puede drenar el saldo |
expired_time | fin del despliegue | auto-expira, no puede persistir |
guardrail_id | una guardrail que enmascara PII | el texto de la solicitud se examina |
firewall_policy_id | lista de permitidos solo con las herramientas que necesita | sin llamadas a herramienta sorpresa |
4. Vincular los dos planos de política
Los dos adjuntos son los campos más potentes de una clave, y se resuelven de manera diferente cuando una política adjunta está deshabilitada:guardrail_id — examen de contenido
guardrail_id — examen de contenido
Examina el texto de la solicitud y la respuesta (PII, secretos,
inyección de prompts) contra una
guardrail ordenada y con alcance de espacio de
trabajo. Resolución: un
guardrail_id explícito y habilitado aplica; uno
deshabilitado es el interruptor de apagado — no hace fallback al
valor por defecto del espacio de trabajo. Sin adjunto, aplica la guardrail
por defecto del espacio de trabajo, si no, nada.firewall_policy_id — aplicación de llamadas a herramienta
firewall_policy_id — aplicación de llamadas a herramienta
Gobierna las acciones que toma un agente — llamadas a herramienta,
despachos MCP, egress — contra una
política de firewall con alcance de espacio de
trabajo. La resolución difiere de las guardrails: una política de firewall
adjunta deshabilitada hace fallback al valor por defecto del espacio
de trabajo, no apaga la aplicación.
is_firewall_gateway — un tipo de clave diferente
is_firewall_gateway — un tipo de clave diferente
Un token con alcance de gateway se acuña solo para las rutas del MCP del
Firewall y del hook de evaluación (
/api/v1/firewall/*), nunca para
inferencia. Una clave normal obtiene 403 ahí. Habilitar este flag, y leer
el texto plano de la clave de gateway, requiere Admin+.5. La sección de claves
Gestionar claves
Crear, editar y revocar claves en la consola.
Rotación
Rota una clave sin tiempo de inactividad.
Claves que expiran
Claves de vida corta para agentes efímeros y ejecuciones de CI.
Enmascarado de claves
Las claves se enmascaran al mostrarse; el texto plano se muestra una vez
al crearlas.
Clave filtrada
Qué hacer en el momento en que una clave queda expuesta.
Lista de verificación de mínima agencia
Pasa cada clave por el mismo proceso de endurecimiento.
6. Dónde encajan las claves en la pila de controles
Una clave con alcance es la primera capa de defensa — decide quién es el llamante y qué puede alcanzar antes de que se ejecute cualquier política. Las Guardrails y el Firewall son las siguientes capas.Asegurar agentes de IA
Por qué la identidad del agente es la base de la pila de controles.
Guardrails vs Firewall
Los dos planos de política a los que una clave puede vincularse.
Agencia excesiva
La amenaza que las claves de mínima agencia están construidas para
contener.