Saltar al contenido principal
Una clave sin restricción de origen es una credencial al portador pura: quien posea la cadena puede presentarla desde cualquier lugar. El campo allow_ips convierte una clave en una clave api con whitelist de ip — solo funciona cuando se presenta desde una dirección de origen que listaste. Una clave filtrada reproducida desde la máquina de un atacante, un proxy residencial o un runner de CI comprometido se rechaza antes de que toque un modelo. Esta es la mitad de vinculación de origen de mínima agencia: model_limits acota qué modelos puede alcanzar una clave, y allow_ips acota desde dónde puede presentarse la clave.

​
1. Qué hace allow_ips

allow_ips contiene una lista de direcciones de origen o rangos CIDR. En cada solicitud, OrcaRouter compara la IP de origen del llamante contra esa lista:
  • Coincidencia → la solicitud procede a las verificaciones de límite de modelo, cuota y política.
  • Sin coincidencia → la solicitud se rechaza en la capa de autenticación con HTTP 403 (access_denied), antes de cualquier llamada a un modelo upstream.
  • Lista vacía → sin restricción; la clave se acepta desde cualquier dirección.
La verificación es la primera puerta que pasa una clave, junto con la validez de la clave — se ejecuta antes de las guardrails, antes del firewall, antes de la medición. Un origen no listado nunca llega a tus políticas ni a tu saldo.
Un allow_ips vacío significa todas las IPs permitidas, no ninguna. Dejarlo en blanco es el valor por defecto sin restricción — fija la clave para que el campo haga algo.

​
2. Formatos aceptados

Cada entrada es una sola IP o un rango CIDR. Mézclalos libremente; lista una entrada por línea.

Dirección única

203.0.113.7 — exactamente un host. Lo mejor para un servidor de IP fija o un gateway NAT con una dirección de egress estable.

Rango CIDR

203.0.113.0/24 — un bloque entero. Lo mejor para una subred de nube, un pool de VPN o un grupo de autoescalado detrás de un CIDR de egress.
Una IP escueta coincide con esa única dirección; un CIDR coincide con cada dirección del bloque. Tanto literales IPv4 como IPv6 se parsean.
Fija al rango más estrecho que aún cubra a cada llamante legítimo. Un host (/32) es más ajustado que un /24; un /24 es más ajustado que “cualquier lugar”. Cada bit que sueltas amplía el conjunto de lugares donde una clave filtrada todavía funciona.

​
3. Establecerlo en la consola

Establece allow_ips en el editor de claves en /console/token. Crear o editar una clave requiere el rol Developer o superior.
  1. Abre Console → API Keys y crea o edita una clave.
  2. En el editor de claves, introduce tus direcciones confiables en el campo IP allow-list — una IP o CIDR por línea.
  3. Guarda. La restricción aplica en la siguiente solicitud que haga esa clave — sin redespliegue, sin cambio de código del agente.
Verifica la dirección de origen real que ve el gateway antes de bloquear una clave. Si tu agente está detrás de un NAT, un balanceador de carga o un proxy de egress, la dirección que OrcaRouter observa es ese salto de egress — no la IP privada del agente. Pon en la lista de permitidos la dirección de egress, y prueba desde el entorno desplegado antes de desplegar.

​
4. Un ejemplo concreto: un agente programado

Un trabajo programado que resume tickets se ejecuta solo desde una subred de nube. Fija su clave a esa subred para que la credencial sea inútil en cualquier otro lugar.
CampoValorEfecto
allow_ips203.0.113.0/24solo el bloque de egress del programador puede presentar esta clave
model_limitsun modelo de resumenno puede escalar a un modelo frontera
credit_limit_usdun techo semanalun bucle descontrolado no puede drenar el saldo
La propia llamada de relay no cambia — sigue usando la clave sk-orca-… como un token al portador: 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Summarize this ticket..."}]
  }'
Presentada desde dentro de 203.0.113.0/24, la llamada procede. Reproduce la misma solicitud exacta desde cualquier otra dirección y el gateway devuelve: 
{
  "error": {
    "message": "您的 IP 不在令牌允许访问的列表中 (request id: ...)",
    "type": "orcarouter_api_error",
    "code": "access_denied"
  }
}
El modelo nunca se llama, no se gasta cuota, y el rechazo se registra.
allow_ips se configura enteramente a través del editor de claves de la consola — una acción de Developer o superior en tu sesión de espacio de trabajo. No hay autoservicio con clave de relay para ello: una clave no puede ampliar su propia lista de orígenes permitidos.

​
5. Qué contiene y qué no contiene una lista de IPs permitidas

Una clave api con whitelist de ip acota desde dónde funciona una clave — una porción del radio de explosión. Se compone con los otros campos de alcance en vez de reemplazarlos.
Una credencial exfiltrada de logs, un commit de git o un portátil vulnerado es peso muerto a menos que el atacante también pueda originar tráfico desde tu rango permitido. Este es el trabajo central del campo — ver clave filtrada para la respuesta a incidentes completa.
Si el compromiso es un host permitido — una dependencia envenenada ejecutándose en tu propio servidor — la verificación de IP de origen pasa. Combina allow_ips con model_limits, un tope de gasto y una política de firewall para que un compromiso de origen confiable siga estando acotado.
Una fijación de IP no hace que una clave sea de vida corta. Combínala con una expiración absoluta y un calendario de rotación para que una clave deje de funcionar desde lugares nuevos y deje de funcionar eventualmente.

​
6. Notas operativas

Si tus llamantes no tienen una dirección de origen estable (serverless con egress rotativo, clientes móviles, redes de oficina amplias), una fijación de IP es el control equivocado — o bloquearías tráfico real o ampliarías el rango hasta que no signifique nada. Apóyate en model_limits, topes de gasto, expiración y adjuntos de política en su lugar.
Editar allow_ips surte efecto en la siguiente solicitud — no hay retraso de propagación que esperar. Cuando añadas una región o migres una subred, actualiza la clave primero, confirma que el nuevo rango funciona, luego deja caer el antiguo.
allow_ips vive en la clave individual, así que cada agente puede tener su propia vinculación de origen. Una clave de programador puede fijarse a una subred de lotes mientras una clave interactiva permite un rango de oficina más amplio — ambas en el mismo espacio de trabajo.

​
7. Próximos pasos

El objeto token

Cada campo en una clave, incluyendo allow_ips, en una referencia.

Límites de modelo

Acota qué modelos puede alcanzar una clave — la otra mitad de la vinculación de origen + alcance.

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.
Una lista de IPs permitidas es el corte de radio de explosión más barato que puedes hacer: un campo, sin cambio de código, y una clave filtrada deja de funcionar desde cualquier lugar donde no debía ejecutarse. Combínala con el resto del modelo de claves con alcance para defensa en profundidad.