Vai al contenuto principale
Una credenziale a vita lunga è una passività che cresce silenziosamente: l’agent viene dismesso, la demo finisce, il contractor se ne va — ma la chiave continua a funzionare finché qualcuno non si ricorda di revocarla. Una chiave API a scadenza capovolge quel default. Imposti una data di fine quando coni la chiave, e OrcaRouter smette di autorizzarla nell’istante in cui quella data passa — nessun task di cleanup da dimenticare, nessuna finestra trapelata ma ancora viva. La scadenza è un campo sul token object: expired_time. Questa pagina è la guida focalizzata su quell’unico controllo. Per il lato cap-di-spesa della stessa schermata, vedi Quota, cap e scadenza.

​
1. Perché impostare una chiave API a scadenza

Il punto di una chiave a tempo è rendere l’esito sicuro quello di default. Alcuni casi in cui ripaga:

Agent effimeri

Un job schedulato o un agent a vita breve riceve una chiave che muore con il ciclo di vita del deployment. Un cron task dimenticato non può continuare a spendere mesi dopo.

Demo e trial

Consegna a un prospect una chiave che funziona per la durata della valutazione e poi si spegne da sola — nessuna revoca di follow-up necessaria.

Contractor e vendor

Dai a una credenziale lo scope della finestra dell’ingaggio. Quando il contratto finisce, finisce anche la chiave.

Accesso con scope sull'incidente

Concedi una chiave ristretta e a vita breve durante un incidente così che l’accesso elevato non possa sopravvivere all’incidente stesso.
La scadenza si abbina naturalmente al resto di una chiave a minima agenzia — un’allow-list di modelli, un’allow-list di IP e un cap di spesa. Ciascuno vincola un asse diverso; insieme mantengono piccolo il raggio d’esplosione di una chiave compromessa. Vedi la Checklist di minima agenzia.

​
2. Il campo expired_time

La scadenza di una chiave vive in un singolo campo sul token object:
CampoTipoSignificato
expired_timeTimestamp Unix (secondi)L’istante assoluto in cui la chiave smette di autorizzare. -1 significa non scade mai.
Due cose da tenere a mente:
  • expired_time è assoluto, non una durata. Imposti il momento in cui la chiave muore, non “tra 30 giorni” — il date picker della console calcola il timestamp per te.
  • Il default per una nuova chiave è -1 (mai). Una chiave scade solo se le dai un timestamp reale; lasciare il campo intatto conia una chiave non a scadenza.
Una chiave non a scadenza (expired_time = -1) è la scelta giusta solo per una credenziale che ruoti attivamente. Se puoi nominare la data in cui una chiave dovrebbe smettere di funzionare — e per agent, demo e contractor di solito puoi — impostala. Una chiave -1 incustodita è quella che con più probabilità sopravvive al suo scopo.

​
3. Impostare una scadenza nella console

Impostare una scadenza è un’azione di console sul tuo token di sessione / accesso — non qualcosa che passi su una chiamata di relay. Creare o modificare una chiave richiede il ruolo Developer o superiore.
  1. Apri Chiavi (/console/token) e crea una nuova chiave, o modificane una esistente.
  2. Nel campo scadenza, scegli la data e l’ora in cui la chiave dovrebbe smettere di funzionare. Lascialo in bianco (o imposta mai) per mantenere la chiave permanente.
  3. Salva. La modifica ha effetto immediatamente — nessun redeploy, nessuna modifica al codice dell’agent.
Modificare la scadenza su una chiave esistente è live: estendi una chiave che sta per scadere, o anticipa la sua scadenza per ritirarla prima, e la nuova deadline si applica alla richiesta successiva.
Solo le chiamate di relay /v1/* portano la chiave sk-orca-…. La scadenza che imposti qui governa quella chiave di relay, ma la configuri dalla sessione di console, mai inviando la chiave di relay a una rotta di gestione.

​
4. Cosa fa una chiave scaduta

Quando una chiave è presentata dopo che il suo expired_time è passato, il gateway la rifiuta al livello di autenticazione — la richiesta non raggiunge mai un modello, quindi non costa quota. Lo stato della chiave passa a Expired, uno degli stati finali automatici che una chiave può raggiungere:
StatoCome si raggiunge
EnabledAttiva; le richieste sono autorizzate.
DisabledL’hai messa in pausa; reversibile.
ExpiredOltre il suo expired_time — raggiunto automaticamente.
ExhaustedOltre la sua quota / cap di spesa — raggiunto automaticamente.
Expired è terminale nel senso che la chiave non autorizzerà di nuovo da sola. Se ti serve indietro, modifica la chiave per spingere expired_time nel futuro (Developer+) e torna a Enabled alla richiesta successiva — la chiave, i suoi limiti e i suoi collegamenti a policy sono tutti preservati. Per ritirare invece una chiave per sempre, revocala.
Scadenza vs. disable vs. revoca. La scadenza è l’interruttore di spegnimento schedulato — decidi la deadline a monte e te ne vai. Disable è la pausa manuale e reversibile per un incidente. Revoca (delete) è permanente. Ricorri alla scadenza ogni volta che sai già quando una credenziale dovrebbe smettere di contare.

​
5. Un esempio svolto: una chiave demo di due settimane

Supponi di dare a un prospect una chiave per una valutazione di 14 giorni. Vuoi che chiami un unico modello economico, spenda non più di un budget fisso, e si spenga quando il trial finisce — tutto senza un promemoria in calendario per revocarla. Nella finestra Nuova chiave, imposta:
  • model_limits: ["openai/gpt-4o-mini"] — la demo non può puntare a un modello più costoso.
  • credit_limit_usd: un budget di trial fisso — un loop incontrollato non può sforarlo.
  • expired_time: la fine della finestra di 14 giorni — la chiave smette di autorizzare da sola quando il trial è finito.
Dopo la deadline, qualsiasi richiesta ulteriore su questa chiave viene rifiutata senza quota spesa, e la chiave mostra Expired nell’elenco. Niente da ripulire per te; la credenziale si è ritirata da sola. 
# Prima della scadenza — autorizzata
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"}]}'

# Dopo la scadenza — la stessa chiamata viene rifiutata al livello di autenticazione,
# il modello non viene mai invocato, e nessuna quota viene consumata.

​
6. Chi può fare cosa

La scadenza è governata dallo stesso role gate del resto del ciclo di vita di una chiave, con scope sul tuo workspace attivo:
AzioneRuolo minimo
Vedere la scadenza di una chiaveViewer
Impostare o cambiare expired_time (creare / modificare una chiave)Developer
Rivelare nuovamente il plaintext di una chiave ordinariaDeveloper
Leggere il plaintext di una chiave con scope gateway (is_firewall_gateway)Admin
Per il ciclo di vita completo — crea, disabilita, revoca — e il pattern di rotazione che si abbina alla scadenza, vedi Gestire le chiavi.

​
7. Prossimi passi

Quota, cap e scadenza

Il fratello cap-di-spesa della scadenza — vincola una chiave per dollari oltre che per tempo.

Rotazione delle chiavi

Il passaggio di consegne zero-downtime che impedisce a una chiave non a scadenza di vivere per sempre.

Il token object

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

Checklist di minima agenzia

Combina la scadenza con limiti sui modelli, allow-list di IP e cap di spesa per una chiave a raggio d’esplosione minimo.
Una chiave che sa quando fermarsi è una credenziale in meno che devi ricordarti di ritirare. Imposta expired_time ogni volta che puoi nominare la data — e lascia che il gateway faccia il cleanup per te.