1. I tre scope
Tre concetti si annidano l’uno nell’altro:- Workspace — il confine del tenant. Ogni membro di un workspace condivide lo stesso catalogo di guardrail e policy del firewall. Nulla attraversa i confini del workspace — una policy scritta nel workspace A è invisibile al workspace B.
- Policy — un set di regole nominato, con scope a livello di workspace (guardrail oppure policy del firewall). Modificare una policy ha effetto su ogni chiave collegata ad essa alla richiesta successiva, senza redeploy.
- Chiave — identità più collegamenti. Una chiave porta i propri vincoli e punta alle policy che la governano.
2. Cosa porta una chiave
Ogni chiave API è un pacchetto di limiti e collegamenti. Impostali nell’editor della chiave (/console/token) — creare o modificare chiavi richiede il ruolo
Developer o superiore.
| Campo | Cosa limita | Ruolo minimo per impostare |
|---|---|---|
model_limits | Limita la chiave a una lista specifica di modelli — qualsiasi chiamata fuori da quella lista viene rifiutata prima di lasciare il gateway. | Developer |
allow_ips | Allowlist di IP. Le richieste da qualsiasi indirizzo non elencato vengono rifiutate al layer di autenticazione. Vuoto significa che tutti gli IP sono consentiti. | Developer |
credit_limit_usd | Tetto di spesa in USD. 0 significa illimitato. Il gateway lo applica rispetto alla spesa lifetime della chiave. | Developer |
expired_time | Timestamp di scadenza assoluto. -1 significa che la chiave non scade mai. | Developer |
environment | Un’etichetta free-form (es. prod, staging, dev) per organizzare le chiavi e filtrare i log. | Developer |
guardrail_id | Collega un guardrail specifico a questa chiave. Ogni chiamata che questa chiave fa viene filtrata da quel guardrail. | Developer |
firewall_policy_id | Collega una policy del firewall specifica a questa chiave. Ogni chiamata a tool che questa chiave emette viene valutata da quella policy. | Developer |
is_firewall_gateway | Segna la chiave come token con scope gateway — richiesto per chiamare le rotte di dispatch MCP e di evaluate hook. Una chiave normale riceve 403 su quelle rotte. Leggere la chiave gateway in chiaro richiede Admin. | Admin (per abilitare e per leggere in chiaro) |
3. Ordine di risoluzione delle policy
Per qualsiasi richiesta, OrcaRouter risolve il guardrail attivo e la policy del firewall indipendentemente:- Collegamento della chiave — se la chiave ha un
guardrail_idesplicito (ofirewall_policy_id) e quella policy esiste ed è abilitata, si applica. - Default del workspace — se la chiave non ha collegamento, si applica il
guardrail (o la policy)
is_defaultabilitata del workspace. - Nessuna applicazione — se nessuno è impostato, la richiesta passa senza filtraggio del contenuto o applicazione delle chiamate a tool.
I due piani differiscono quando una policy collegata è disabilitata:
- Un collegamento guardrail disabilitato o eliminato significa che la chiave non riceve nessun guardrail — disabilitarlo è lo switch di spegnimento; non fa fallback al default del workspace.
- Un collegamento firewall disabilitato fa fallback alla policy del firewall di default del workspace — quindi disabilitare un collegamento del firewall riporta la chiave al default del workspace, non disattiva l’applicazione.
0/non impostato) fa sempre fallback al default del
workspace; né l’uno né l’altro impostato significa nessuna applicazione.4. Chiavi a minima agenzia — una chiave per agent
La configurazione più sicura è dare a ogni agent la propria chiave con scope ristretto invece di condividere un’unica chiave del workspace tra tutti i chiamanti. Una chiave ben configurata per un agent che chiama solo un modello ed esegue task pianificati potrebbe essere:model_limits:["openai/gpt-4o-mini"]— l’agent non può passare a un modello più costoso o più capace.allow_ips: il CIDR di egress dello scheduler — nessun’altra sorgente può presentare questa chiave.credit_limit_usd: un tetto di budget settimanale — un loop incontrollato non può esaurire il saldo del workspace.expired_time: la fine dello sprint o del ciclo di vita del deployment — la chiave scade automaticamente e non può essere riutilizzata.guardrail_id: un guardrail specifico per la sensibilità dei dati di questo agent — più restrittivo del default del workspace.firewall_policy_id: una policy che consente solo i tool di cui questo agent ha legittimamente bisogno.
Crea chiavi con scope gateway (
is_firewall_gateway) solo per la superficie
di dispatch MCP o evaluate hook — mai per il traffico di inferenza generale. Una
chiave gateway sul percorso di inferenza dà al chiamante accesso alle rotte
/api/v1/firewall/*, che è una capability più ampia di quella di cui ha
bisogno. Una chiave, uno scopo.5. Dove vengono scritte le policy
I Guardrails e le policy del firewall sono entrambi con scope a livello di workspace e condivisi tra tutti i membri, ma le modifiche richiedono il ruolo corretto:- Leggi qualsiasi guardrail, policy o chiave — qualsiasi membro del workspace.
- Crea o modifica guardrail, policy del firewall, MCP server, livelli di autonomia, azioni di approvazione e chiavi API ordinarie — Developer+.
- Abilita
is_firewall_gatewaysu una chiave; leggi la chiave gateway in chiaro — Admin+.
6. Prossimi passi
Baseline Secure Agents
La postura di partenza consigliata — un switch del livello di autonomia,
poi ottimizza dal traffico reale.
Ottieni una chiave API
Crea la tua prima chiave e collega un guardrail o una policy del firewall
nella console.