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.

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<n>). 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-<YYYY>-<NN>, 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: @<unix_epoch>: la data di deprecazione come data strutturata RFC 9745;
• Sunset: <IMF-fixdate>: la data di rimozione (RFC 8594);
• Link: <doc_url>; rel="deprecation" e Link: <doc_url>; 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: <package>/<version> (<runtime>/<version>) 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.