1. Perché chiavi API con scope per gli agent LLM
Una chiave API generica è una credenziale bearer: chiunque la possieda può chiamare qualsiasi modello, da qualunque luogo, per qualsiasi importo, senza alcuna policy collegata. È l’opposto di ciò di cui un agent autonomo ha bisogno. Su OrcaRouter, una chiave API non è solo una credenziale — è una dichiarazione di scope. Ogni chiave porta i propri vincoli (quali modelli, quali IP, quanta spesa, quando scade) e punta al guardrail e alla policy del firewall che governano il suo traffico. Modificare la policy a cui una chiave punta ha effetto alla richiesta successiva, senza redeploy e senza modifiche al codice dell’agent. Il principio è la minima agenzia: dai a ogni agent l’identità più ristretta che gli consenta comunque di svolgere il suo lavoro, e niente di più. Una chiave, un agent, uno scopo.2. Cosa porta una chiave con scope
Ogni chiave è un insieme di limiti più due collegamenti a policy. Ogni campo è documentato sulla propria pagina — i link spoke qui sotto portano alla profondità.Limiti sui modelli
model_limits restringe una chiave a un elenco nominato di modelli. Una
chiamata al di fuori dell’elenco viene rifiutata prima di lasciare il
gateway — l’agent non può passare a un modello più costoso o più capace.IP allow-list
allow_ips fissa una chiave a indirizzi sorgente specifici. Una chiave
trapelata presentata da qualunque altro luogo viene rifiutata al livello di
autenticazione.Quota, cap e scadenza
credit_limit_usd limita la spesa complessiva (0 = illimitata);
expired_time imposta una scadenza assoluta (-1 = mai).Environment
environment è un’etichetta libera (prod, staging, dev) per
organizzare le chiavi e filtrare i log.Collegare le policy
guardrail_id e firewall_policy_id collegano alla chiave una policy sui
contenuti e una policy sulle chiamate a tool. Nessun collegamento fa
fallback al default del workspace.Il token object
Il riferimento completo campo per campo di una chiave, inclusi
remain_quota / used_quota e is_firewall_gateway.Bounded vs unbounded. Una chiave con
credit_limit_usd: 0 e
expired_time: -1 non ha cap di spesa e non scade mai — comoda, ma il peggior
raggio d’esplosione se trapela. Vedi
illimitate vs limitate per capire
quando ciascuna è appropriata.3. Una chiave a minima agenzia concreta
Un agent schedulato che riassume i ticket di supporto con un unico modello economico e gira da un solo host non ha quasi bisogno di agenzia. Una chiave ben con scope per esso:| Campo | Valore | Perché |
|---|---|---|
model_limits | un modello di summarization | non può escalare a un modello di frontiera |
allow_ips | il CIDR di egress dello scheduler | una chiave trapelata è inutile altrove |
credit_limit_usd | un tetto settimanale | un loop incontrollato non può prosciugare il saldo |
expired_time | fine del deployment | si auto-scade, non può attardarsi |
guardrail_id | un guardrail che maschera le PII | il testo della richiesta viene filtrato |
firewall_policy_id | mette in allow-list solo i tool che servono | nessuna chiamata a tool a sorpresa |
4. Collegare i due piani di policy
I due collegamenti sono i campi più potenti su una chiave, e si risolvono in modo diverso quando una policy collegata è disabilitata:guardrail_id — filtro dei contenuti
guardrail_id — filtro dei contenuti
Filtra il testo di richiesta e risposta (PII, segreti, prompt
injection) rispetto a un guardrail con scope a
livello di workspace e ordinato. Risoluzione: un
guardrail_id esplicito e
abilitato si applica; uno disabilitato è l’interruttore di spegnimento —
non fa fallback al default del workspace. Senza collegamento, si applica
il guardrail di default del workspace, altrimenti nulla.firewall_policy_id — applicazione sulle chiamate a tool
firewall_policy_id — applicazione sulle chiamate a tool
Governa le azioni che un agent compie — chiamate a tool, dispatch MCP,
egress — rispetto a una policy del firewall con
scope a livello di workspace. La risoluzione differisce dai guardrail: una
policy del firewall collegata e disabilitata fa fallback al default
del workspace, non disattiva l’applicazione.
is_firewall_gateway — un tipo di chiave diverso
is_firewall_gateway — un tipo di chiave diverso
Un token con scope gateway è coniato solo per le rotte del Firewall MCP e
dell’evaluate-hook (
/api/v1/firewall/*), mai per l’inferenza. Una chiave
normale riceve 403 lì. Abilitare questo flag, e leggere il plaintext della
chiave gateway, richiede Admin+.5. La sezione chiavi
Gestire le chiavi
Crea, modifica e revoca le chiavi nella console.
Rotazione
Ruota una chiave senza downtime.
Chiavi a scadenza
Chiavi a vita breve per agent effimeri ed esecuzioni di CI.
Mascheramento delle chiavi
Le chiavi sono mascherate quando vengono mostrate; il plaintext è mostrato
una sola volta alla creazione.
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.
6. Dove si collocano le chiavi nel control stack
Una chiave con scope è il primo layer di difesa — decide chi è il chiamante e cosa può raggiungere prima che giri qualsiasi policy. I Guardrails e il Firewall sono i layer successivi.Proteggere gli agent AI
Perché l’identità dell’agent è la fondazione del control stack.
Guardrails vs Firewall
I due piani di policy a cui una chiave può collegarsi.
Agenzia eccessiva
La minaccia che le chiavi a minima agenzia sono costruite per contenere.