Vai al contenuto principale
Una chiave senza restrizione sulla sorgente è una pura credenziale bearer: chiunque possieda la stringa può presentarla da qualunque luogo. Il campo allow_ips trasforma una chiave in una chiave API con ip whitelist — funziona solo quando è presentata da un indirizzo sorgente che hai elencato. Una chiave trapelata riprodotta dalla macchina di un attaccante, da un proxy residenziale o da un runner di CI compromesso viene rifiutata prima ancora di toccare un modello. Questa è la metà di binding sulla sorgente della minima agenzia: model_limits limita quali modelli una chiave può raggiungere, e allow_ips limita da dove la chiave può essere presentata.

​
1. Cosa fa allow_ips

allow_ips contiene un elenco di indirizzi sorgente o range CIDR. A ogni richiesta, OrcaRouter confronta l’IP sorgente del chiamante con quell’elenco:
  • Match → la richiesta procede ai controlli su limiti dei modelli, quota e policy.
  • Nessun match → la richiesta viene rifiutata al livello di autenticazione con HTTP 403 (access_denied), prima di qualsiasi chiamata a un modello upstream.
  • Elenco vuoto → nessuna restrizione; la chiave è accettata da qualunque indirizzo.
Il controllo è il primo gate che una chiave supera, insieme alla validità della chiave — gira prima dei guardrail, prima del firewall, prima del metering. Una sorgente non elencata non raggiunge mai le tue policy né il tuo saldo.
Un allow_ips vuoto significa tutti gli IP consentiti, non nessuno. Lasciarlo in bianco è il default non ristretto — fissa la chiave perché il campo faccia qualcosa.

​
2. Formati accettati

Ogni voce è un singolo IP oppure un range CIDR. Mescola entrambi liberamente; elenca una voce per riga.

Indirizzo singolo

203.0.113.7 — esattamente un host. Ideale per un server a IP fisso o un gateway NAT con un indirizzo di egress stabile.

Range CIDR

203.0.113.0/24 — un intero blocco. Ideale per una subnet cloud, un pool VPN o un autoscaling group dietro un unico CIDR di egress.
Un IP nudo corrisponde a quell’unico indirizzo; un CIDR corrisponde a ogni indirizzo nel blocco. Sia i literal IPv4 sia gli IPv6 vengono interpretati.
Fissa al range più ristretto che copra comunque ogni chiamante legittimo. Un host (/32) è più stretto di un /24; un /24 è più stretto di “ovunque”. Ogni bit che togli allarga l’insieme dei luoghi da cui una chiave trapelata funziona ancora.

​
3. Impostalo nella console

Imposta allow_ips nell’editor delle chiavi su /console/token. Creare o modificare una chiave richiede il ruolo Developer o superiore.
  1. Apri Console → Chiavi API e crea o modifica una chiave.
  2. Nell’editor della chiave, inserisci i tuoi indirizzi fidati nel campo IP allow-list — un IP o CIDR per riga.
  3. Salva. La restrizione si applica alla prossima richiesta che quella chiave fa — nessun redeploy, nessuna modifica al codice dell’agent.
Verifica l’indirizzo sorgente reale che il gateway vede prima di bloccare una chiave. Se il tuo agent sta dietro un NAT, un load balancer o un proxy di egress, l’indirizzo che OrcaRouter osserva è quell’hop di egress — non l’IP privato dell’agent. Metti in allow-list l’indirizzo di egress, e testa dall’ambiente di deployment prima di rilasciare.

​
4. Un esempio concreto: un agent schedulato

Un job schedulato che riassume i ticket gira solo da una subnet cloud. Fissa la sua chiave a quella subnet così che la credenziale sia inutile altrove.
CampoValoreEffetto
allow_ips203.0.113.0/24solo il blocco di egress dello scheduler può presentare questa chiave
model_limitsun modello di summarizationnon può escalare a un modello di frontiera
credit_limit_usdun tetto settimanaleun loop incontrollato non può prosciugare il saldo
La chiamata di relay in sé è invariata — usa comunque la chiave sk-orca-… come token bearer: 
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..."}]
  }'
Presentata dall’interno di 203.0.113.0/24, la chiamata procede. Riproduci la stessa identica richiesta da qualunque altro indirizzo e il gateway restituisce: 
{
  "error": {
    "message": "您的 IP 不在令牌允许访问的列表中 (request id: ...)",
    "type": "orcarouter_api_error",
    "code": "access_denied"
  }
}
Il modello non viene mai chiamato, nessuna quota viene spesa, e il rifiuto è loggato.
allow_ips è configurato interamente tramite l’editor delle chiavi della console — un’azione Developer-o-superiore sulla tua sessione di workspace. Non c’è self-service tramite chiave di relay per esso: una chiave non può allargare la propria allow-list sulla sorgente.

​
5. Cosa contiene e cosa non contiene un’IP allow-list

Una chiave API con ip whitelist vincola da dove una chiave funziona — una fetta del raggio d’esplosione. Si compone con gli altri campi di scope anziché sostituirli.
Una credenziale esfiltrata dai log, da un commit git o da un laptop violato è peso morto a meno che l’attaccante non possa anche originare traffico dal tuo range in allow-list. È il compito centrale del campo — vedi chiave trapelata per la risposta completa all’incidente.
Se la compromissione è un host in allow-list — una dipendenza avvelenata in esecuzione sul tuo stesso server — il controllo dell’IP sorgente passa. Abbina allow_ips a model_limits, un cap di spesa e una policy del firewall così che una compromissione da sorgente fidata resti comunque limitata.
Un IP pin non rende una chiave a vita breve. Combinalo con una scadenza assoluta e con uno schedule di rotazione così che una chiave smetta di funzionare sia da nuovi luoghi sia eventualmente del tutto.

​
6. Note operative

Se i tuoi chiamanti non hanno un indirizzo sorgente stabile (serverless con egress rotante, client mobili, ampie reti d’ufficio), un IP pin è il controllo sbagliato — o blocchi traffico reale o allarghi il range finché non è privo di senso. Appoggiati invece a model_limits, cap di spesa, scadenza e collegamenti a policy.
Modificare allow_ips ha effetto alla richiesta successiva — non c’è ritardo di propagazione da attendere. Quando aggiungi una region o migri una subnet, aggiorna prima la chiave, conferma che il nuovo range funzioni, poi togli quello vecchio.
allow_ips vive sulla singola chiave, così ogni agent può avere il proprio binding sulla sorgente. Una chiave di scheduler può fissare a una subnet batch mentre una chiave interattiva consente un range d’ufficio più ampio — entrambe nello stesso workspace.

​
7. Prossimi passi

Il token object

Ogni campo su una chiave, incluso allow_ips, in un unico riferimento.

Limiti sui modelli

Limita quali modelli una chiave può raggiungere — l’altra metà del binding sorgente + scope.

Chiave trapelata

Cosa fare nell’istante in cui una chiave è esposta.

Checklist di minima agenzia

Fai passare ogni chiave attraverso lo stesso giro di hardening.
Un’IP allow-list è il taglio al raggio d’esplosione più economico che puoi fare: un campo, nessuna modifica al codice, e una chiave trapelata smette di funzionare da ovunque non fosse destinata a girare. Abbinala al resto del modello delle chiavi con scope per una difesa in profondità.