# Politica di versionamento e deprecazione delle API Questa pagina spiega come KeenAuth gestisce le versioni delle sue API, come viene annunciata una rimozione e per quanto tempo gli SDK, la CLI, il provider Terraform/OpenTofu e il server MCP ricevono correzioni di sicurezza. Ogni annuncio viene pubblicato nel [registro delle modifiche](/docs/changelog). ## Versioni dell'API L'API di gestione riporta la versione principale nel percorso (`/v1`). All'interno di `v1` vengono apportate solo modifiche additive: - un nuovo endpoint; - un nuovo campo di richiesta facoltativo; - un nuovo campo di risposta; - un nuovo valore di enum; - un nuovo codice di errore; - un nuovo tipo di evento. Scrivi la tua integrazione in modo che accetti queste aggiunte. Una modifica incompatibile viene apportata solo in una nuova versione principale (`/v2`). Le modifiche incompatibili sono: rimuovere o rinominare un campo, cambiare un tipo, aggiungere un campo obbligatorio, cambiare il comportamento predefinito e cambiare la paginazione, l'ordinamento o il valore predefinito di `limit`. `v1` resta disponibile per almeno 24 mesi dopo la disponibilità generale di `v2`. KeenAuth non usa intestazioni di versione basate sulla data; la versione principale nel percorso e la regola delle sole modifiche additive costituiscono l'intero contratto. ### Operazioni beta e GA Ogni operazione è contrassegnata con `x-idp-stability: beta` o `x-idp-stability: ga` nel documento OpenAPI. Un'operazione `beta` può cambiare durante una beta privata o pubblica e non è soggetta alle regole di deprecazione riportate sotto; le sue risposte includono l'intestazione `Idp-Stability: beta`. Un'operazione `ga` è congelata: cambia solo secondo le regole di questa pagina. ### Eventi e claim del token - I tipi di evento per i clienti hanno una versione dello schema (`v`). Una modifica incompatibile a un payload crea una nuova versione dello schema; le due versioni vengono consegnate in parallelo per 365 giorni e ogni endpoint webhook sceglie la versione che riceve. - Aggiungere un claim al token è una modifica additiva. Rimuovere un claim o cambiarne il significato viene annunciato con 365 giorni di anticipo, e `claims_supported` viene aggiornato nel documento di discovery. ## Deprecazione e rimozione La rimozione di un endpoint, un parametro, un claim, uno scope, un tipo di evento, un algoritmo di firma o un'altra superficie viene annunciata nel registro delle modifiche almeno 365 giorni prima della data di rimozione. Ogni deprecazione ha un identificatore nella forma `dep--`, una data di deprecazione, una data di rimozione (sunset), un sostituto se esiste e una guida alla migrazione. **Eccezione di sicurezza:** per chiudere una vulnerabilità di sicurezza, il comportamento all'interno di `v1` può cambiare senza il preavviso di 365 giorni. Una modifica di questo tipo viene pubblicata nel registro delle modifiche con il tag `security` e gli ambienti interessati vengono avvisati via e-mail. ### Segnali nelle risposte dell'API La risposta di un'operazione in fase di rimozione contiene: - `Deprecation: @`: la data di deprecazione come data strutturata RFC 9745; - `Sunset: `: la data di rimozione (RFC 8594); - `Link: ; rel="deprecation"` e `Link: ; rel="sunset"`: la guida alla migrazione. Dopo la data di rimozione l'operazione risponde `410` con il codice di problema `endpoint_sunset`. Le rimozioni del protocollo OAuth e OpenID Connect (un algoritmo di firma, un metodo di autenticazione del client, un parametro) non possono includere intestazioni; vengono conteggiate per client e passano per le stesse notifiche. ### Dove vedere il tuo utilizzo - **Log dell'ambiente:** un record `deprecation_notice`, al massimo una volta all'ora, con `deprecation_id`, `client_id` e `sunset_at`. - **Dashboard:** la pagina Deprecazioni mostra gli ultimi 30 giorni per deprecazione, client e versione dell'SDK; da 90 giorni prima della data di rimozione compare un banner. - **API:** `GET /v1/reports/deprecation-usage?from=&to=` (autorizzazione `reports:read`). - **E-mail:** ai ruoli `owner` e `admin` dell'account e al contatto tecnico dell'ambiente, il giorno dell'annuncio (ogni ambiente che usa la superficie) e 180, 90, 30 e 7 giorni prima della data di rimozione (ambienti che l'hanno usata negli ultimi 30 giorni). Gli SDK ufficiali, la CLI, il provider e il server MCP inviano `Idp-Client: / (/)` con ogni richiesta. L'intestazione non è un'autenticazione; serve solo al conteggio e un valore malformato viene ignorato. I conteggi di utilizzo non memorizzano indirizzi IP, `User-Agent` né identificatori degli utenti finali. ## Politica di supporto per SDK e strumenti Gli SDK, la CLI, il provider Terraform/OpenTofu e il server MCP seguono il versionamento semantico. Una versione principale aumenta solo con una modifica incompatibile del linguaggio stesso o con una nuova versione principale dell'API. - La linea di prodotti nel suo insieme riceve supporto di sicurezza per almeno 5 anni, a partire dalla sua disponibilità generale. - Le correzioni di sicurezza vengono rilasciate nell'ultima versione principale di ogni pacchetto e l'aggiornamento a essa è gratuito. - La versione principale precedente riceve correzioni di sicurezza e di bug critici per 12 mesi dopo la disponibilità generale della nuova versione principale; poi raggiunge la fine del ciclo di vita. - Ogni aggiornamento di sicurezza pubblicato resta disponibile per almeno 10 anni, o per il resto del periodo di supporto se è più lungo. - Da 90 giorni prima della fine del ciclo di vita, un SDK scrive nel log della tua applicazione un avviso con l'intestazione `Deprecation` del server e la propria data di fine del ciclo di vita. - Le versioni dell'SDK a fine ciclo di vita non vengono bloccate dal server; la dashboard e l'e-mail ti avvisano. - La fine del supporto viene annunciata nel registro delle modifiche e nel registro dei pacchetti (npm `deprecate`; su PyPI una descrizione, la release non viene ritirata). ### Supporto degli ambienti di esecuzione Gli SDK supportano le versioni degli ambienti di esecuzione che i rispettivi fornitori supportano ancora con correzioni di sicurezza: Node.js LTS, Python secondo il calendario di supporto upstream, le ultime due release di Go, Java 17 e 21, .NET LTS, PHP 8.2 e successive, Ruby 3.2 e successive, iOS 16 e successive, Android API 26 e successive. La matrice minima degli ambienti di esecuzione viene pubblicata con ogni versione principale. Un ambiente di esecuzione che perde il supporto del fornitore viene abbandonato in una versione minore, annunciata nel registro delle modifiche con 90 giorni di anticipo.