Politique de versionnage et d'obsolescence de l'API

Cette page explique comment KeenAuth versionne ses API, comment une suppression est annoncée et pendant combien de temps les SDK, la CLI, le fournisseur Terraform/OpenTofu et le serveur MCP reçoivent des correctifs de sécurité. Chaque annonce est publiée dans le journal des modifications.

Versions de l'API

L'API de gestion porte sa version majeure dans le chemin (/v1). Dans v1, seules des modifications additives sont apportées :

• un nouveau point de terminaison ;
• un nouveau champ de requête facultatif ;
• un nouveau champ de réponse ;
• une nouvelle valeur d'énumération ;
• un nouveau code d'erreur ;
• un nouveau type d'événement.

Écrivez votre intégration de façon à accepter ces ajouts.

Une modification incompatible n'est apportée que dans une nouvelle version majeure (/v2). Les modifications incompatibles sont : supprimer ou renommer un champ, changer un type, ajouter un champ obligatoire, changer le comportement par défaut, et changer la pagination, le tri ou la valeur par défaut de limit. v1 reste disponible au moins 24 mois après la disponibilité générale de v2.

KeenAuth n'utilise pas d'en-têtes de version fondés sur une date ; la version majeure dans le chemin et la règle des seules modifications additives forment tout le contrat.

Opérations bêta et GA

Chaque opération est marquée x-idp-stability: beta ou x-idp-stability: ga dans le document OpenAPI. Une opération beta peut changer pendant une bêta privée ou publique et n'est pas couverte par les règles d'obsolescence ci-dessous ; ses réponses portent l'en-tête Idp-Stability: beta. Une opération ga est figée : elle ne change que selon les règles de cette page.

Événements et claims de jeton

• Les types d'événements client portent une version de schéma (v<n>). Une modification incompatible d'une charge utile crée une nouvelle version de schéma ; les deux versions sont livrées en parallèle pendant 365 jours et chaque point de terminaison de webhook choisit la version qu'il reçoit.
• Ajouter un claim au jeton est une modification additive. Supprimer un claim ou en changer le sens est annoncé 365 jours à l'avance, et claims_supported est mis à jour dans le document de découverte.

Obsolescence et suppression

La suppression d'un point de terminaison, d'un paramètre, d'un claim, d'un scope, d'un type d'événement, d'un algorithme de signature ou d'une autre surface est annoncée dans le journal des modifications au moins 365 jours avant la date de suppression. Chaque obsolescence a un identifiant de la forme dep-<YYYY>-<NN>, une date d'obsolescence, une date de suppression (sunset), un remplacement lorsqu'il existe et un guide de migration.

Exception de sécurité : pour corriger une vulnérabilité de sécurité, le comportement dans v1 peut changer sans le préavis de 365 jours. Une telle modification est publiée dans le journal des modifications avec l'étiquette security, et les environnements concernés sont avertis par e-mail.

Signaux dans les réponses de l'API

La réponse d'une opération en cours de suppression porte :

• Deprecation: @<unix_epoch> : la date d'obsolescence sous forme de date structurée RFC 9745 ;
• Sunset: <IMF-fixdate> : la date de suppression (RFC 8594) ;
• Link: <doc_url>; rel="deprecation" et Link: <doc_url>; rel="sunset" : le guide de migration.

Après la date de suppression, l'opération répond 410 avec le code de problème endpoint_sunset. Les suppressions du protocole OAuth et OpenID Connect (un algorithme de signature, une méthode d'authentification du client, un paramètre) ne peuvent pas porter d'en-têtes ; elles sont comptées par client et passent par les mêmes notifications.

Où voir votre utilisation

• Journal de l'environnement : un enregistrement deprecation_notice, au plus une fois par heure, avec deprecation_id, client_id et sunset_at.
• Tableau de bord : la page Obsolescences montre les 30 derniers jours par obsolescence, client et version de SDK ; un bandeau apparaît à partir de 90 jours avant la date de suppression.
• API : GET /v1/reports/deprecation-usage?from=&to= (permission reports:read).
• E-mail : aux rôles owner et admin du compte et au contact technique de l'environnement, le jour de l'annonce (chaque environnement qui utilise la surface) et 180, 90, 30 et 7 jours avant la date de suppression (environnements qui l'ont utilisée au cours des 30 derniers jours).

Les SDK officiels, la CLI, le fournisseur et le serveur MCP envoient Idp-Client: <package>/<version> (<runtime>/<version>) avec chaque requête. Cet en-tête n'est pas une authentification ; il sert uniquement au comptage, et une valeur mal formée est ignorée. Les comptages d'utilisation ne stockent ni adresse IP, ni User-Agent, ni identifiant d'utilisateur final.

Politique de support des SDK et des outils

Les SDK, la CLI, le fournisseur Terraform/OpenTofu et le serveur MCP suivent le versionnage sémantique. Une version majeure n'augmente qu'avec une modification incompatible du langage lui-même ou avec une nouvelle version majeure de l'API.

• La gamme de produits dans son ensemble reçoit un support de sécurité d'au moins 5 ans, à compter de sa disponibilité générale.
• Les correctifs de sécurité sont publiés dans la dernière version majeure de chaque paquet, et la mise à niveau vers celle-ci est gratuite.
• La version majeure précédente reçoit des correctifs de sécurité et de bogues critiques pendant 12 mois après la disponibilité générale de la nouvelle version majeure ; elle arrive ensuite en fin de vie.
• Chaque mise à jour de sécurité publiée reste disponible au moins 10 ans, ou pendant le reste de la période de support si celui-ci est plus long.
• À partir de 90 jours avant la fin de vie, un SDK écrit un avertissement dans le journal de votre application avec l'en-tête Deprecation du serveur et sa propre date de fin de vie.
• Les versions de SDK en fin de vie ne sont pas bloquées par le serveur ; le tableau de bord et l'e-mail vous avertissent.
• La fin du support est annoncée dans le journal des modifications et dans le registre de paquets (npm deprecate ; sur PyPI une description, la version n'est pas retirée).

Prise en charge des environnements d'exécution

Les SDK prennent en charge les versions d'environnement d'exécution que leurs éditeurs maintiennent encore avec des correctifs de sécurité : Node.js LTS, Python selon le calendrier de support amont, les deux dernières versions de Go, Java 17 et 21, .NET LTS, PHP 8.2 et ultérieur, Ruby 3.2 et ultérieur, iOS 16 et ultérieur, Android API 26 et ultérieur. La matrice minimale des environnements d'exécution est publiée avec chaque version majeure. Un environnement d'exécution qui perd le support de son éditeur est abandonné dans une version mineure, annoncée dans le journal des modifications 90 jours à l'avance.