Rotazione chiavi API OpenAI: il piano operativo contro gli stop

OpenAI ha introdotto la data di scadenza per le chiavi API di progetto il 10 settembre 2026. Da quel momento, la rotazione chiavi API OpenAI è diventata manutenzione programmata di produzione: un agente non presidiato deve avere un responsabile, una finestra per la sostituzione e una verifica prima che la chiave scada.

Rotazione chiavi API OpenAI: c'è una scadenza, non un automatismo

Una chiave API è il segreto con cui un'applicazione dimostra di essere autorizzata a usare l'API OpenAI. Spesso viene salvata in un secret manager, collegata a un processo pianificato e poi lasciata lì finché qualcosa non smette di funzionare.

Quando si crea una chiave API di progetto, OpenAI consente ora di impostarne la data di scadenza. Un amministratore può anche definire una durata massima in Platform settings, a livello di organizzazione o di progetto. Se la policy è attiva, ogni nuova chiave deve scadere entro il limite previsto.

I controlli hanno funzioni diverse:

Il vincolo gerarchico è importante. Un'impostazione di progetto non può prolungare la validità di una chiave oltre quanto consente la policy dell'organizzazione: deve sempre restare entro quel perimetro.

Non è un sistema di rotazione automatica. Nelle indicazioni per la produzione, OpenAI raccomanda di creare una sostituta prima della scadenza, aggiornare le applicazioni, verificarne il funzionamento e solo dopo revocare la vecchia chiave. Ogni passaggio di consegne resta responsabilità del team.

Il vero cambiamento per l'azienda è il budget di manutenzione

La funzionalità non modifica il prezzo dei token. Cambia invece il costo in lavoro e il rischio di interruzione per ogni attività pianificata che si autentica con una chiave di progetto.

Un semplice modello aiuta a pianificare. I valori che seguono sono ipotesi sul carico di lavoro, non limiti imposti da OpenAI.

Si consideri un progetto con un agente eseguito ogni 15 minuti, cioè 96 volte al giorno. Una rotazione programmata richiede 30 minuti di lavoro operativo. Con una cadenza trimestrale e un costo complessivo dell'operatore di $75 l'ora, ogni rotazione costa $37.50, per un totale di $150 all'anno per progetto. Su dieci progetti, la manutenzione diventa una voce annua ben visibile da $1,500.

Si immagini invece che una scadenza passi inosservata e causi uno stop di 4 ore. In quella finestra saltano 16 avvii pianificati. Se per controllare e rieseguire ogni attività servono 10 minuti, il ripristino richiede 160 minuti, ovvero 2 ore e 40 minuti. Alla stessa tariffa di $75, il solo lavoro costa $200, senza ancora considerare consegne ai clienti in ritardo, report mancati o ricavi persi.

È questo l'effetto operativo. La scadenza riduce il tempo durante il quale una credenziale dimenticata può restare valida, ma trasforma un rischio di sicurezza nascosto in un'attività ricorrente. Servono spazio nel budget e un responsabile indicato in calendario.

Se il problema reale è una spesa API fuori controllo, la scadenza della chiave non è lo strumento adatto. La guida separata sui controlli di budget per le API degli agenti AI tratta quel limite. Un tetto di spesa e una scadenza delle credenziali possono entrambi interrompere il lavoro, ma rispondono a problemi diversi e richiedono piani di ripristino distinti.

Chi dovrebbe adottare questo workflow

Un founder solitario con un agente SaaS non presidiato

Chi gestisce da solo un riepilogo dell'assistenza, un elaboratore di documenti o un'attività di arricchimento dati dovrebbe assegnare la credenziale a un responsabile, anche quando coincide con il founder. Occorre annotare quale scheduler, deployment e voce del secret store usano la chiave. La sostituzione va avviata mentre la credenziale corrente funziona ancora, per poi osservare il completamento di una vera esecuzione pianificata con il nuovo segreto.

Il vantaggio è la continuità: la rotazione diventa una piccola release pianificata, invece di essere il cliente a segnalare che il lavoro del giorno precedente non è mai arrivato.

Un responsabile operativo di agenzia con progetti cliente

Un'agenzia può associare a ogni progetto cliente un registro della rotazione con progetto, responsabile della chiave, attività distribuite, scadenza, stato della sostituzione ed esito della verifica. In questo modo il lavoro diventa misurabile e un'automazione dimenticata non resta nascosta dentro una credenziale condivisa che nessuno vuole modificare.

Il vantaggio è la tutela del margine. Il tempo necessario alla rotazione entra nella pianificazione delle consegne e chi segue l'account sa quali attività del cliente controllare prima che il vecchio segreto scompaia.

Un platform team che definisce la regola dell'organizzazione

Un team backend o di piattaforma dovrebbe stabilire prima la durata massima dell'organizzazione, lasciando poi ai singoli progetti un limite compatibile. Dove carico di lavoro o rischio lo richiedono, il progetto può adottare una policy più breve; non può però usare una durata maggiore per aggirare il tetto dell'organizzazione.

Il vantaggio è una governance coerente. La procedura di sostituzione dovrebbe essere pubblicata insieme alla regola sulla durata: una scadenza senza passaggio di consegne è soltanto un futuro incidente con una data già fissata.

Un amministratore della sicurezza che riordina le vecchie credenziali

Per un amministratore della sicurezza, la policy sulle nuove chiavi e l'inventario di quelle vecchie sono due percorsi distinti. Prima si applica la durata massima alle credenziali appena create; poi si individuano separatamente le chiavi di progetto esistenti e si assegna loro un responsabile. La documentazione pubblicata non promette che queste ultime scadano da sole.

Il vantaggio è un'adozione trasparente. L'organizzazione migliora subito la gestione delle nuove credenziali senza scambiare una policy rivolta al futuro per una bonifica già completata.

Come ruotare una chiave senza creare interruzioni

I pulsanti esatti dipendono dal servizio di hosting e dal secret manager. La sequenza sicura, invece, non cambia.

1. 1

   Verificare la policy e il responsabile

   Prima di creare la sostituta, controllare il limite massimo dell'organizzazione e quello del progetto. Registrare il progetto della chiave corrente, tutte le attività che la usano, la persona responsabile e il momento in cui inizia la sostituzione.

2. 2

   Creare in anticipo la nuova chiave

   Creare una nuova chiave API di progetto quando quella vecchia è ancora valida. La scadenza della sostituta deve rispettare la policy attiva. La chiave non va inserita nel codice sorgente né in un repository pubblico.

3. 3

   Predisporla tramite il secret store

   Salvare la sostituta come nuova versione nella variabile d'ambiente o nel percorso del sistema di gestione dei segreti già usato dall'applicazione. Aggiornare prima un worker controllato o un percorso di test. OpenAI supporta anche progetti distinti per staging e produzione quando serve un isolamento più forte fra test e attività operative.

4. 4

   Verificare l'attività distribuita

   Eseguire l'applicazione attraverso il suo reale percorso di autenticazione. Controllare l'esito della richiesta, l'output dell'attività, la coda e i log del worker. Dopo aver abilitato il tracciamento delle chiavi, la pagina Usage di OpenAI può offrire un segnale aggiuntivo, ma una dashboard non sostituisce la verifica del risultato aziendale.

5. 5

   Completare il rollout, poi ritirare la vecchia chiave

   Aggiornare ogni deployment, scheduler, segreto CI e worker a esecuzione prolungata che utilizzava la vecchia credenziale. Verificare che la nuova chiave funzioni per tutte queste attività. Revocare quella vecchia soltanto al termine dei controlli.

Cosa resta comunque a carico del team

Le pagine pubbliche di OpenAI non indicano una durata predefinita universale né un unico limite massimo. Non descrivono neppure un periodo di tolleranza, un meccanismo di sostituzione automatica o un calendario delle notifiche di scadenza. La policy è quella definita nelle impostazioni dell'account; promemoria e rollout dipendono invece dal processo operativo costruito intorno a essa.

L'impostazione non può nemmeno sapere dove è stato copiato un segreto. Non rileva che uno sviluppatore abbia incollato la chiave in un sistema CI, in un ambiente serverless, su un computer locale e in uno script di backup. L'inventario è la parte che molti team tenderanno a sottovalutare.

Anche la verifica è delicata. Una richiesta di test riuscita dimostra che la sostituta è valida, non che sia arrivata a tutti i worker pianificati. Per questo l'elenco delle attività deve comparire nel registro della rotazione e la vecchia chiave deve restare valida finché l'intera lista non è stata controllata.

Cosa fare questa settimana

È il momento di intervenire se un agente pianificato, un batch worker, un'automazione per i clienti o un servizio backend usa una chiave API di progetto e l'organizzazione intende applicare una durata massima. Il lavoro di rotazione va inserito nel budget operativo prima che la policy generi la prima scadenza.

L'adozione completa può aspettare se non è attiva alcuna durata massima e nessuna chiave di progetto corrente ha una data di scadenza. Conviene comunque inventariare subito credenziali e responsabili. Il nuovo controllo rende chiara la direzione futura e OpenAI raccomanda già una rotazione regolare.

Poiché le chiavi esistenti non vengono descritte come soggette a scadenza retroattiva, non c'è motivo di sostenere che ogni vecchio deployment debba affrontare improvvisamente una scadenza a settembre. Non è un invito a ignorarle: significa che vanno esaminate a parte, senza affidare alla nuova policy la bonifica del passato.

Lunedì, scegliere un progetto di produzione. Assegnare la credenziale a un responsabile, predisporre una sostituta mentre la chiave corrente funziona ancora, controllare ogni attività distribuita con la nuova chiave e infine ritirare quella vecchia. Questi quattro passaggi costituiscono il piano di rotazione.

Per ricevere altre guide operative in linguaggio chiaro, iscriviti alla newsletter.