# Postman コレクションと OpenAPI ドキュメント

KeenAuth は、機械可読な API の仕様を 2 つのファイルとして公開しています。どちらも、リリースごとに公開管理 API の定義から生成されるため、API リファレンスと常に一致します。内部操作はこれらのファイルには含まれません。

| ファイル | 形式 | ダウンロード |
|---|---|---|
| Postman コレクション | Postman Collection v2.1.0 | [postman_collection.json](/api/postman_collection.json) |
| OpenAPI ドキュメント | OpenAPI 3.1 | [openapi.json](/api/openapi.json) |

## Postman にインポートする

1. Postman で **Import** を選択し、ダウンロードした `postman_collection.json` を選択します。
2. コレクション変数を開き、`apiKey` に管理 API キーを設定します。キーはダッシュボードまたは CLI で作成できます。キーは Bearer トークンとして送信されます。
3. `region` にご利用環境のリージョンを設定します（既定値は `eu` です）。リクエストは、ホスト `api.{{region}}.keenauth.com`、パス `/v1` に送信されます。
4. リクエストを送信します。すべての `POST` リクエストには `Idempotency-Key` ヘッダーが付与され、Postman が新しい GUID を設定します。そのため、再試行されたリクエストも安全です。

リクエストは、API タグごとに 1 つのフォルダーにまとめられています。`{{user_id}}` などのパスパラメーターはコレクション変数です。必要なリクエストを送信する前に、値を設定してください。

## OpenAPI ドキュメントを使用する

OpenAPI ドキュメントは、コード生成や、API ゲートウェイ、リンター、モックサーバーの入力として使用します。同じドキュメントは、API 自体の `https://api.eu.keenauth.com/v1/openapi.json` でも提供されています。

## 仕様のアーカイブと SDK のダイジェスト

OpenAPI ドキュメントは、コンテンツアドレス方式のアーカイブパスでも公開されています。パスのセグメントはドキュメントのバイト列の SHA-256 であるため、アーカイブパスのファイルが変更されることはありません。

| ファイル | 内容 |
|---|---|
| `/openapi/<sha256>/openapi.json` | ドキュメント。該当バージョンの `/api/openapi.json` とバイト単位で同一です |
| `/openapi/<sha256>/openapi.json.sha256` | `sha256sum` 形式のダイジェスト |
| [`/openapi/index.json`](/openapi/index.json) | アーカイブされたドキュメントの一覧: `sha256`、`info_version`、`path`。最新のものは `current` で示されます |

各サーバー SDK には、生成元となったドキュメントのダイジェストが記録されています。

| SDK | 記録箇所 |
|---|---|
| Node.js（`@keenauth/node`） | `OPENAPI_SHA256` のエクスポートと `package.json` の `keenauth.openapiSha256` |
| Python（`keenauth-python`） | `keenauth.OPENAPI_SHA256` と、パッケージメタデータの `OpenAPI document` プロジェクト URL |
| Go | `keenauth.OpenAPISHA256` |

ダウンロードしたファイルを確認するには、両方のファイルがあるフォルダーで `sha256sum -c openapi.json.sha256` を実行します。ダイジェストを SDK が報告する値と比較すると、その SDK がどの API バージョンに対してビルドされたかを確認できます。