Vai al contenuto principale
Una chiave è l’identità che ogni richiesta porta con sé. Nel corso della sua vita la crei, magari la metti in pausa durante un incidente, e infine la ritiri. Questa pagina percorre l’intero ciclo di vita nella console — il modo più rapido per gestire le chiavi API senza toccare codice né rieseguire alcun deploy. Per l’insieme completo dei vincoli che una chiave porta (allow-list di modelli, allow-list di IP, cap di spesa, collegamenti a policy), vedi Il token object e Collegare le policy a una chiave. Questa pagina riguarda il ciclo di vita: crea → disabilita → revoca.
Tutte e tre le azioni vivono nella schermata Chiavi della console (/console/token). Creare, modificare, disabilitare o eliminare una chiave richiede il ruolo Developer o superiore; qualsiasi ruolo (Viewer in su) può leggere l’elenco.

​
1. Creare una chiave

Una nuova chiave nasce con scope. Anziché coniare un’unica credenziale ampia e condividerla, dai a ogni agent o servizio la propria chiave con esattamente i limiti di cui ha bisogno — è ciò che mantiene piccolo il raggio d’esplosione di un agent compromesso (vedi Checklist di minima agenzia). Nella console, apri Chiavi → Nuova chiave e imposta:
Un nome leggibile da un umano e un’etichetta environment a forma libera (prod, staging, dev, o quel che preferisci) per cui potrai poi filtrare i log. Vedi Environment.
Allow-list di modelli, allow-list di IP, un cap di spesa in USD e una scadenza — ciascuno opzionale, ciascuno restringe ciò che la chiave può fare. Vedi Limiti sui modelli, IP allow-list e Quota, cap e scadenza.
Un guardrail (guardrail_id) e una policy del firewall (firewall_policy_id) per governare i contenuti e le chiamate a tool di questa chiave. Vedi Collegare le policy.
La chiave in plaintext (sk-orca-…) è mostrata esattamente una volta, alla creazione. Copiala in quel momento. Dopodiché la console mostra sempre e solo una forma mascherata. Puoi rivelare nuovamente il plaintext di una chiave ordinaria in seguito (Developer+), ma il plaintext di una chiave con scope gateway richiede Admin — quindi salvalo in un posto sicuro la prima volta.
Usa la nuova chiave per l’inferenza esattamente come faresti con qualsiasi chiave OrcaRouter: 
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":"ping"}]}'
Solo le chiamate di relay /v1/* usano la chiave sk-orca-…. Le azioni di console in questa pagina girano sul tuo token di sessione / accesso, non sulla chiave di relay.

​
2. Disabilitare una chiave (la pausa reversibile)

Quando una chiave si comporta male — un loop incontrollato, una credenziale trapelata che stai ancora indagando, un servizio che stai mettendo offline per manutenzione — non devi eliminarla. Disabilitarla porta lo stato della chiave su off, così ogni richiesta che fa viene rifiutata, mentre la chiave, i suoi limiti, i suoi collegamenti a policy e la sua cronologia d’uso restano tutti intatti. Nell’elenco Chiavi, porta lo stato della chiave su Disabled. Per riabilitarla in seguito, riportalo indietro. Una chiave può trovarsi in uno di questi stati:
StatoSignificato
EnabledAttiva; le richieste sono autorizzate.
DisabledMessa in pausa da te; le richieste sono rifiutate finché non riabiliti.
ExpiredOltre il suo expired_time; raggiunto automaticamente.
ExhaustedHa raggiunto la sua quota / cap di spesa; raggiunto automaticamente.
Disable è il tuo pulsante di pausa per la risposta agli incidenti. Se sospetti che una chiave sia compromessa ma vuoi conservare la sua config e i suoi log mentre indaghi, disabilitala prima e indaga — poi riabilitala o revocala. Vedi Risposta a una chiave trapelata.
Expired ed Exhausted si raggiungono da soli — una chiave oltre la sua scadenza o oltre il suo cap di spesa smette di autorizzare senza alcuna azione da parte tua.

​
3. Revocare una chiave (permanente)

Quando una chiave ha esaurito il suo scopo — l’agent è dismesso, la credenziale è confermata trapelata, il progetto è stato rilasciato — revocala eliminandola. È permanente: la credenziale non può mai più autorizzare una richiesta, e una chiave eliminata non è recuperabile. Emetti una chiave nuova per qualsiasi sostituzione. Nell’elenco Chiavi, scegli Elimina sulla chiave (Developer+). Per ripulirne diverse in una volta, selezionale ed eliminale in batch.
Disable è reversibile; delete no. Se c’è qualche possibilità che ti serva ancora la chiave — o la sua config e cronologia — disabilitala invece. Elimina solo quando sei certo che la credenziale debba cessare di esistere. Per un leak confermato, eliminare immediatamente taglia fuori la credenziale per sempre; disabilitare ti dà il tempo di indagare prima.

​
4. Rivelare nuovamente e ruotare

Il plaintext di una chiave è mascherato ovunque nella console dopo la creazione. Un Developer+ può rivelare nuovamente il plaintext di una chiave ordinaria su richiesta; rivelare nuovamente una chiave con scope gateway (is_firewall_gateway) richiede Admin. La rotazione è il pattern del passaggio di consegne sicuro: crea la chiave sostitutiva, sposta il tuo traffico su di essa, poi disabilita (e in seguito elimina) quella vecchia — così non c’è mai una finestra senza una chiave funzionante. Il passo-passo completo vive in Rotazione delle chiavi.

​
5. Chi può fare cosa

Ogni azione del ciclo di vita è role-gated rispetto al tuo workspace attivo:
AzioneRuolo minimo
Vedere l’elenco delle chiaviViewer
Creare / modificare / disabilitare / eliminare una chiaveDeveloper
Rivelare nuovamente il plaintext di una chiave ordinariaDeveloper
Abilitare is_firewall_gateway, o leggere il plaintext di una chiave gatewayAdmin
Lo scoping a livello di workspace significa che una chiave creata in un workspace non è mai visibile né utilizzabile da un altro. Per come chiavi, policy e workspace si annidano, vedi Scope e chiavi.

​
6. Prossimi passi

Il token object

Ogni campo che una chiave porta, e cosa ciascuno vincola.

Collegare le policy a una chiave

Collega un guardrail e una policy del firewall così il traffico della chiave è governato.

Rotazione delle chiavi

Il passaggio di consegne zero-downtime da una vecchia chiave a una nuova.

Risposta a una chiave trapelata

Cosa fare nell’istante in cui sospetti che una chiave sia esposta.
Il ciclo di vita è deliberatamente semplice: crea ristretto, disabilita per mettere in pausa, elimina per revocare. Più ristretta è ciascuna chiave e più rapidamente puoi metterla in pausa o ritirarla, più piccolo è il raggio d’esplosione quando un singolo agent viene compromesso.