Richtlinie zu API-Versionierung und Abkündigung

Diese Seite erklärt, wie KeenAuth seine APIs versioniert, wie eine Entfernung angekündigt wird und wie lange die SDKs, die CLI, der Terraform/OpenTofu-Provider und der MCP-Server Sicherheitskorrekturen erhalten. Jede Ankündigung wird im Änderungsprotokoll veröffentlicht.

API-Versionen

Die Management-API trägt ihre Hauptversion im Pfad (/v1). Innerhalb von v1 gibt es nur additive Änderungen:

• ein neuer Endpunkt;
• ein neues optionales Anfragefeld;
• ein neues Antwortfeld;
• ein neuer Enum-Wert;
• ein neuer Fehlercode;
• ein neuer Ereignistyp.

Schreiben Sie Ihre Integration so, dass sie diese Ergänzungen akzeptiert.

Eine inkompatible Änderung erfolgt nur in einer neuen Hauptversion (/v2). Inkompatible Änderungen sind: ein Feld entfernen oder umbenennen, einen Typ ändern, ein Pflichtfeld hinzufügen, das Standardverhalten ändern sowie Paginierung, Sortierung oder den Standardwert von limit ändern. v1 bleibt nach der allgemeinen Verfügbarkeit von v2 mindestens 24 Monate verfügbar.

KeenAuth verwendet keine datumsbasierten Versions-Header; die Hauptversion im Pfad und die Regel „nur additive Änderungen“ sind der gesamte Vertrag.

Beta- und GA-Operationen

Jede Operation ist im OpenAPI-Dokument mit x-idp-stability: beta oder x-idp-stability: ga gekennzeichnet. Eine beta-Operation kann sich während einer privaten oder öffentlichen Beta ändern und unterliegt nicht den unten stehenden Abkündigungsregeln; ihre Antworten tragen den Header Idp-Stability: beta. Eine ga-Operation ist eingefroren: Sie ändert sich nur nach den Regeln dieser Seite.

Ereignisse und Token-Claims

• Kundenereignistypen tragen eine Schemaversion (v<n>). Eine inkompatible Änderung an einer Nutzlast erzeugt eine neue Schemaversion; beide Versionen werden 365 Tage parallel zugestellt, und jeder Webhook-Endpunkt wählt die Version, die er empfängt.
• Das Hinzufügen eines Token-Claims ist additiv. Das Entfernen eines Claims oder die Änderung seiner Bedeutung wird 365 Tage im Voraus angekündigt, und claims_supported im Discovery-Dokument wird aktualisiert.

Abkündigung und Entfernung

Die Entfernung eines Endpunkts, Parameters, Claims, Scopes, Ereignistyps, Signaturalgorithmus oder einer anderen Oberfläche wird im Änderungsprotokoll mindestens 365 Tage vor dem Entfernungsdatum angekündigt. Jede Abkündigung hat eine Kennung der Form dep-<YYYY>-<NN>, ein Abkündigungsdatum, ein Entfernungsdatum (Sunset), einen Ersatz, sofern vorhanden, und einen Migrationsleitfaden.

Sicherheitsausnahme: Um eine Sicherheitslücke zu schließen, kann sich das Verhalten innerhalb von v1 ohne die Ankündigungsfrist von 365 Tagen ändern. Eine solche Änderung wird im Änderungsprotokoll mit dem Tag security veröffentlicht, und die betroffenen Umgebungen werden per E-Mail benachrichtigt.

Signale in API-Antworten

Die Antwort einer Operation, die entfernt wird, enthält:

• Deprecation: @<unix_epoch>: das Abkündigungsdatum als strukturiertes Datum nach RFC 9745;
• Sunset: <IMF-fixdate>: das Entfernungsdatum (RFC 8594);
• Link: <doc_url>; rel="deprecation" und Link: <doc_url>; rel="sunset": den Migrationsleitfaden.

Nach dem Entfernungsdatum antwortet die Operation mit 410 und dem Problemcode endpoint_sunset. Entfernungen im OAuth- und OpenID-Connect-Protokoll (ein Signaturalgorithmus, eine Client-Authentifizierungsmethode, ein Parameter) können keine Header tragen; sie werden pro Client gezählt und durchlaufen dieselben Benachrichtigungen.

Wo Sie Ihre Nutzung sehen

• Umgebungsprotokoll: ein deprecation_notice-Eintrag, höchstens einmal pro Stunde, mit deprecation_id, client_id und sunset_at.
• Dashboard: Die Seite „Abkündigungen“ zeigt die letzten 30 Tage nach Abkündigung, Client und SDK-Version; ab 90 Tagen vor dem Entfernungsdatum erscheint ein Banner.
• API: GET /v1/reports/deprecation-usage?from=&to= (Berechtigung reports:read).
• E-Mail: an die Rollen owner und admin des Kontos und an den technischen Kontakt der Umgebung, am Tag der Ankündigung (jede Umgebung, die die Oberfläche nutzt) sowie 180, 90, 30 und 7 Tage vor dem Entfernungsdatum (Umgebungen, die sie in den letzten 30 Tagen genutzt haben).

Die offiziellen SDKs, die CLI, der Provider und der MCP-Server senden mit jeder Anfrage Idp-Client: <package>/<version> (<runtime>/<version>). Der Header ist keine Authentifizierung; er dient nur der Zählung, und ein fehlerhaft formatierter Wert wird ignoriert. Nutzungszählungen speichern weder IP-Adresse noch User-Agent noch eine Endbenutzerkennung.

Supportrichtlinie für SDKs und Werkzeuge

Die SDKs, die CLI, der Terraform/OpenTofu-Provider und der MCP-Server folgen der semantischen Versionierung. Eine Hauptversion steigt nur bei einer inkompatiblen Änderung der Sprache selbst oder mit einer neuen Hauptversion der API.

• Die Produktlinie als Ganzes erhält mindestens 5 Jahre Sicherheitsunterstützung, gerechnet ab ihrer allgemeinen Verfügbarkeit.
• Sicherheitskorrekturen erscheinen in der neuesten Hauptversion jedes Pakets, und das Upgrade darauf ist kostenlos.
• Die vorherige Hauptversion erhält nach der allgemeinen Verfügbarkeit der neuen Hauptversion 12 Monate lang Sicherheitskorrekturen und Korrekturen kritischer Fehler; danach endet ihr Support.
• Jedes veröffentlichte Sicherheitsupdate bleibt mindestens 10 Jahre verfügbar oder für den Rest des Supportzeitraums, falls dieser länger ist.
• Ab 90 Tagen vor dem Supportende schreibt ein SDK eine Warnung mit dem Deprecation-Header des Servers und seinem eigenen Supportende-Datum in das Protokoll Ihrer Anwendung.
• SDK-Versionen nach dem Supportende werden vom Server nicht blockiert; Dashboard und E-Mail warnen Sie.
• Das Supportende wird im Änderungsprotokoll und in der Paketregistry angekündigt (npm deprecate; auf PyPI eine Beschreibung, die Version wird nicht zurückgezogen).

Unterstützte Laufzeitumgebungen

Die SDKs unterstützen die Laufzeitversionen, die ihre Hersteller noch mit Sicherheitskorrekturen versorgen: Node.js LTS, Python gemäß dem Upstream-Supportplan, die letzten beiden Go-Versionen, Java 17 und 21, .NET LTS, PHP 8.2 und neuer, Ruby 3.2 und neuer, iOS 16 und neuer, Android API 26 und neuer. Die Mindestmatrix der Laufzeitumgebungen wird mit jeder Hauptversion veröffentlicht. Eine Laufzeitumgebung, die die Unterstützung ihres Herstellers verliert, wird in einer Nebenversion entfernt; dies wird 90 Tage im Voraus im Änderungsprotokoll angekündigt.