Vai al contenuto principale
Ogni credenziale a vita lunga dovrebbe essere sostituita su uno schedule, e immediatamente a ogni sospetto di esposizione. Il modo sicuro per ruotare le credenziali di una chiave API non è mai mutare una chiave viva sul posto — è coniarne una nuova, spostarci il traffico, e ritirare quella vecchia una volta che nulla dipende più da essa. Fatto in quell’ordine non c’è mai un momento senza una chiave funzionante. Questa pagina è il playbook passo-passo. Per il ciclo di vita più ampio delle chiavi (crea / disabilita / elimina) vedi Gestire le chiavi; per ogni campo che una chiave porta vedi Il token object.
Tutte le azioni di console qui vivono nella schermata Chiavi (/console/token) e girano sul tuo token di sessione / accesso — non sulla chiave di relay. Creare, modificare, disabilitare o eliminare una chiave richiede il ruolo Developer o superiore. Solo le chiamate di inferenza /v1/* usano la chiave di relay sk-orca-….

​
1. Perché ruotare, e perché mai sul posto

Una chiave su OrcaRouter è un’identità immutabile, non solo una stringa — porta la propria allow-list di modelli, allow-list di IP, cap di spesa, scadenza e collegamenti a policy. Non puoi cambiare il materiale segreto di una chiave esistente; la credenziale e i vincoli sono emessi insieme alla creazione. Quindi “ruotare” significa emettere un successore e migrarci sopra. Fallo:
  • su una cadenza fissa per qualsiasi credenziale di produzione (trimestrale è una baseline comune);
  • nell’istante in cui una chiave è sospettata trapelata — anche se per un leak confermato, tagliala fuori prima e ruota dopo (vedi Risposta a una chiave trapelata);
  • ogni volta che il proprietario della chiave (un dipendente, un’integrazione di vendor, un agent dismesso) cambia.
Il plaintext (sk-orca-…) è mostrato una volta, alla creazione — copialo in quel momento. Dopodiché la console mostra solo una forma mascherata come orca-7Bf****wxyz. Un Developer+ può rivelare nuovamente il plaintext di una chiave ordinaria in seguito, ma una chiave con scope gateway (is_firewall_gateway) richiede Admin per rileggere il suo plaintext — quindi tratta la prima rivelazione della chiave gateway come la tua unica copia affidabile.

​
2. La sequenza di rotazione della chiave API

Tutto il punto è una sovrapposizione pulita: la nuova chiave funziona prima che quella vecchia si fermi. Quattro passi.
1

Crea la chiave successore

Conia una nuova chiave con lo stesso scope di quella che stai sostituendo — gli stessi model_limits, allow_ips, credit_limit_usd, expired_time, e gli stessi guardrail_id / firewall_policy_id. Copia il plaintext immediatamente. La rotazione è il momento ideale anche per restringere lo scope: togli un modello che l’agent non usa più, o stringi l’allow-list di IP.
2

Migra il traffico

Deploya la nuova sk-orca-… su ogni chiamante — config, secret manager, variabile di CI, runtime dell’agent. Falla uscire nello stesso modo in cui rilasci qualsiasi modifica a un segreto. Entrambe le chiavi sono vive a questo punto, così i deployment possono essere scaglionati senza un outage.
3

Verifica che la nuova chiave stia portando carico

Conferma che il successore stia effettivamente servendo traffico prima di toccare quello vecchio. Osserva il used_quota della nuova chiave salire mentre quello della vecchia si appiattisce — l’uso per chiave è il tuo segnale di cutover.
4

Ritira la vecchia chiave

Una volta che la vecchia chiave non mostra traffico, disabilitala prima (reversibile) e tieni d’occhio i ritardatari, poi eliminala per sempre. Disable è la pausa; delete è il punto di non ritorno.
Imposta un’etichetta environment su ogni chiave — riusala tra la vecchia e la nuova chiave, o incrementala (prod → prod-2026q2) — così che successore e predecessore siano etichettati distintamente mentre entrambi sono vivi durante la finestra di sovrapposizione.

​
3. Una rotazione concreta, via REST

Tutto qui sotto è un’azione di console — queste rotte di gestione girano sotto la tua sessione (UserAuth), non sulla chiave di relay. Supponi di stare sostituendo la chiave per un agent di summarization schedulato. Crea il successore con lo stesso scope: 
# Token di sessione della console — NON una chiave di relay sk-orca-…
curl https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "summarizer-2026q2",
    "environment": "prod",
    "model_limits_enabled": true,
    "model_limits": "openai/gpt-4o-mini",
    "credit_limit_usd": 50,
    "expired_time": -1,
    "guardrail_id": 12,
    "firewall_policy_id": 7
  }'
La risposta restituisce il plaintext una volta ("data": "sk-orca-…"). Copialo, deployalo sul summarizer, e conferma che la nuova chiave stia servendo prima di proseguire. Quando la vecchia chiave (id 481) non mostra traffico, disabilita poi elimina: 
# Metti in pausa prima (reversibile) — imposta lo stato della vecchia chiave a Disabled (2)
curl -X PUT https://api.orcarouter.ai/api/token \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{"id": 481, "status": 2}'

# Una volta che sei sicuro che nulla dipende da essa — revoca per sempre
curl -X DELETE https://api.orcarouter.ai/api/token/481 \
  -H "Authorization: Bearer <your-session-token>"
Lo stato di una chiave è uno tra Enabled (1), Disabled (2), Expired (3) o Exhausted (4). Disabilitare lo porta a Disabled; ogni richiesta che la chiave fa viene poi rifiutata mentre la sua config, i suoi collegamenti e la sua cronologia restano intatti. Eliminare è permanente — la credenziale non può mai più autorizzare una richiesta, e una chiave eliminata non è recuperabile.
Puoi fare tutto questo senza l’API — la schermata Chiavi ha Nuova chiave, un interruttore Disabled per chiave, e Elimina (singola o batch). La forma REST qui sopra è per scriptare rotazioni schedulate.

​
4. Ruotare chiavi collegate a policy e chiavi gateway

I collegamenti a guardrail e firewall di una chiave vivono sulla chiave, quindi il successore deve portare gli stessi guardrail_id e firewall_policy_id per applicare la stessa postura. Due cose da sapere:
Guardrail e policy del firewall sono risorse nominate con scope a livello di workspace, condivise tra le chiavi. Ruotare una chiave non tocca la policy stessa; stai solo ri-puntando una chiave nuova ai guardrail_id / firewall_policy_id esistenti. La policy continua a governare il traffico ininterrottamente.
Una chiave con is_firewall_gateway impostato guida le rotte del Gateway del Firewall (/api/v1/firewall/*). Coniarne una, e rivelarne nuovamente il plaintext, richiedono entrambe Admin. Poiché non puoi rileggere casualmente il suo segreto, cattura il plaintext della nuova chiave gateway alla creazione e memorizzalo nel tuo secret manager prima di fare il cutover.
Non riutilizzare una singola chiave — gateway o altro — tra molti agent e “ruotare” modificando i limiti. Una chiave per agent mantiene ogni rotazione isolata e il raggio d’esplosione piccolo. Vedi la Checklist di minima agenzia.

​
5. Rotazione d’emergenza (sospetto leak)

Se pensi che una chiave sia esposta, l’ordine si capovolge: ferma prima l’emorragia, migra dopo.
  1. Disabilita la chiave sospetta subito così che non possa autorizzare nulla mentre indaghi — oppure eliminala del tutto se il leak è confermato.
  2. Conia il successore e fallo uscire come in §2.
  3. Rivedi cosa ha fatto la chiave trapelata prima di tagliarla: filtra i request log per quella chiave (token) per delimitare il raggio d’esplosione.
Il runbook completo dell’incidente è su Risposta a una chiave trapelata.
Un expired_time breve è un’assicurazione di rotazione: una chiave a scadenza si ritira da sola anche se dimentichi la rotazione manuale, limitando per quanto a lungo una singola credenziale possa mai essere abusata.

​
6. Prossimi passi

Gestire le chiavi

Il ciclo di vita crea / disabilita / revoca su cui questi passi si basano.

Collegare le policy a una chiave

Porta lo stesso guardrail e la stessa policy del firewall sul successore.

Chiavi a scadenza

Imposta una scadenza così che le chiavi si ruotino da sole a una deadline.

Risposta a una chiave trapelata

Il percorso d’emergenza quando una credenziale è esposta.
La rotazione è solo sovrapposizione disciplinata: un successore che funziona prima che il predecessore si fermi. Mantieni ogni chiave con scope ristretto e il passaggio di consegne resta noioso — che è esattamente ciò che vuoi da una rotazione di credenziale.