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

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

## 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 日前に変更履歴で告知されます。