API のバージョン管理と非推奨ポリシー

このページでは、KeenAuth が API のバージョンをどのように管理するか、削除をどのように告知するか、そして SDK、CLI、Terraform/OpenTofu プロバイダー、MCP サーバーがどれだけの期間セキュリティ修正を受けられるかを説明します。すべての告知は変更履歴で公開されます。

API のバージョン

管理 API はパスにメジャーバージョン（/v1）を含みます。v1 の中では追加的な変更のみを行います。

新しいエンドポイント
新しい任意のリクエストフィールド
新しいレスポンスフィールド
新しい enum 値
新しいエラーコード
新しいイベントタイプ

これらの追加を受け入れられるように連携を実装してください。

互換性を壊す変更は新しいメジャーバージョン（/v2）でのみ行います。互換性を壊す変更とは、フィールドの削除や名前の変更、型の変更、必須フィールドの追加、デフォルト動作の変更、およびページネーション、並び順、デフォルトの limit の変更です。v1 は v2 の一般提供開始後、少なくとも 24 か月間利用できます。

KeenAuth は日付ベースのバージョンヘッダーを使用しません。パス内のメジャーバージョンと、追加的な変更のみというルールが契約のすべてです。

ベータ版と GA の操作

OpenAPI ドキュメントでは、すべての操作に x-idp-stability: beta または x-idp-stability: ga が付いています。beta の操作はプライベートまたはパブリックベータの間に変更されることがあり、以下の非推奨ルールの対象外です。そのレスポンスには Idp-Stability: beta ヘッダーが付きます。ga の操作は凍結されており、このページのルールに従ってのみ変更されます。

イベントとトークンのクレーム

顧客向けイベントタイプはスキーマバージョン（v<n>）を持ちます。ペイロードに互換性を壊す変更を加えると新しいスキーマバージョンが作られ、両方のバージョンが 365 日間並行して配信されます。各 Webhook エンドポイントは受け取るバージョンを選択します。
トークンへのクレームの追加は追加的な変更です。クレームの削除や意味の変更は 365 日前に告知され、ディスカバリードキュメントの claims_supported が更新されます。

非推奨と削除

エンドポイント、パラメーター、クレーム、スコープ、イベントタイプ、署名アルゴリズム、その他の対象の削除は、削除日の少なくとも 365 日前に変更履歴で告知されます。すべての非推奨には dep-<YYYY>-<NN> 形式の識別子、非推奨日、削除日（sunset）、代替がある場合はその代替、および移行ガイドがあります。

セキュリティ上の例外: セキュリティ脆弱性を修正するため、v1 の動作が 365 日の告知なしに変更されることがあります。このような変更は security タグ付きで変更履歴に公開され、影響を受ける環境にはメールで通知されます。

API レスポンスのシグナル

削除予定の操作のレスポンスには次が含まれます。

Deprecation: @<unix_epoch>: RFC 9745 の構造化日付による非推奨日
Sunset: <IMF-fixdate>: 削除日（RFC 8594）
Link: <doc_url>; rel="deprecation" と Link: <doc_url>; rel="sunset": 移行ガイド

削除日以降、その操作は問題コード endpoint_sunset とともに 410 を返します。OAuth と OpenID Connect のプロトコルにおける削除（署名アルゴリズム、クライアント認証方式、パラメーター）はヘッダーを付けられないため、クライアントごとに集計され、同じ通知経路をたどります。

利用状況の確認場所

環境ログ: 1 時間に最大 1 回、deprecation_id、client_id、sunset_at を含む deprecation_notice レコード
ダッシュボード: 非推奨ページに直近 30 日間の状況を非推奨、クライアント、SDK バージョンごとに表示します。削除日の 90 日前からバナーが表示されます。
API: GET /v1/reports/deprecation-usage?from=&to=（権限 reports:read）
メール: アカウントの owner と admin のロール、および環境の技術担当者宛てに、告知日（その対象を利用するすべての環境）と、削除日の 180、90、30、7 日前（直近 30 日間に利用した環境）に送信されます。

公式 SDK、CLI、プロバイダー、MCP サーバーは、すべてのリクエストに Idp-Client: <package>/<version> (<runtime>/<version>) を付けて送信します。このヘッダーは認証ではなく集計にのみ使われ、形式に合わない値は無視されます。利用状況の集計には IP アドレス、User-Agent、エンドユーザーの識別子は保存されません。

SDK とツールのサポートポリシー

SDK、CLI、Terraform/OpenTofu プロバイダー、MCP サーバーはセマンティックバージョニングに従います。メジャーバージョンは、言語自体に互換性を壊す変更があった場合、または API の新しいメジャーバージョンが出た場合にのみ上がります。

製品ライン全体として、一般提供開始から少なくとも 5 年間セキュリティサポートを提供します。
セキュリティ修正は各パッケージの最新メジャーバージョンでリリースされ、そのバージョンへのアップグレードは無料です。
1 つ前のメジャーバージョンは、新しいメジャーバージョンの一般提供開始後 12 か月間、セキュリティ修正と重大なバグ修正を受け、その後サポート終了となります。
公開されたすべてのセキュリティ更新は、少なくとも 10 年間、またはサポート期間の残りがそれより長い場合はその期間、入手可能な状態に保たれます。
サポート終了の 90 日前から、SDK はサーバーの Deprecation ヘッダーと自身のサポート終了日を、アプリケーションのログに警告として書き込みます。
サポートが終了した SDK バージョンはサーバー側でブロックされません。ダッシュボードとメールで警告します。
サポート終了は変更履歴とパッケージレジストリで告知されます（npm では deprecate、PyPI では説明文で告知し、リリースは取り下げません）。

ランタイムのサポート

SDK は、各ベンダーがまだセキュリティ修正を提供しているランタイムバージョンをサポートします。Node.js LTS、アップストリームのサポートスケジュールに従う Python、Go の最新 2 リリース、Java 17 と 21、.NET LTS、PHP 8.2 以降、Ruby 3.2 以降、iOS 16 以降、Android API 26 以降です。最小ランタイムマトリックスはメジャーバージョンごとに公開されます。ベンダーのサポートが終了したランタイムはマイナーバージョンでサポート対象から外され、そのことは 90 日前に変更履歴で告知されます。