# 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](/docs/changelog) 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`). 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--`, 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: @`: das Abkündigungsdatum als strukturiertes Datum nach RFC 9745; - `Sunset: `: das Entfernungsdatum (RFC 8594); - `Link: ; rel="deprecation"` und `Link: ; 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: / (/)`. 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.