# 接続のリビジョンを一覧表示

`GET /v1/connections/{connection_id}/revisions` · 権限 `connections:read`

エンタープライズ接続（SAML または OIDC）のリビジョンを、新しいものから順に一覧表示します。保留中のドラフト（最大 1 件）と、過去 90 日以内に公開または破棄されたリビジョンが含まれます。

**有効な**接続では、セキュリティ上重要な変更はすぐには適用されません。代わりに**ドラフトリビジョン**になり、ドラフトをテストして公開するまで、有効な構成はそのまま維持されます。

- ID プロバイダのエンティティ ID や SSO URL を変更する、または署名のピン留めを削除する SAML メタデータのインポート（[メタデータをインポート](import-metadata.md)）
- OIDC の `issuer` または `client_id` の変更（[OIDC 構成を設定](../connection-oidc/put.md)）
- 接続のステータスに関係なく行われるすべての SP ホストの移行（[SP ホストを移行](migrate-sp-host.md)）

ドラフトは、[接続をテスト](test.md)し、その `revision_id` を使ってテストしてから、[公開](publish-revision.md)してください。新しいドラフトを作成すると、以前のドラフトは破棄されます（`discard_reason: superseded`）。

リビジョンに表示されるのは、新しい機密ではない値（`changes`）のみです。新しい OIDC クライアントシークレットは `client_secret_change`（`keep`、`replace`、`clear`）としてのみ表示されます。シークレットとその末尾の文字は返されません。リビジョンを作成または決定したユーザーは、ここではなく管理の監査ログ（`connection.revision_created`、`connection.revision_published`）に記録されます。

## リクエスト

| フィールド | 種類 | 必須 | 説明 |
|---|---|---|---|
| `connection_id` | パス | はい | エンタープライズ接続 ID（`conn_…`）。 |
| `limit` | クエリ | いいえ | ページサイズ（1〜100、既定値 20）。 |
| `after` | クエリ | いいえ | `list_metadata.after` のカーソル。カーソルは、それを生成した接続に対してのみ有効です。 |

リストは前方向にのみページングされます。`before` と `order` はサポートされていません（`422`）。

## レスポンス

`200 OK`:

```json
{
  "data": [
    {
      "id": "connrev_01j9xr8c2d4e6f8g0h2j4k6m8n",
      "connection_id": "conn_01j9xp6q0r1s5t7v9w1x3y5z7b",
      "protocol": "saml",
      "kind": "sp_host",
      "status": "draft",
      "discard_reason": null,
      "created_at": "2026-10-28T10:00:00Z",
      "decided_at": null,
      "purge_after": null,
      "superseded_revision_id": null,
      "changes": {
        "sp_host": "login.example.com",
        "idp_entity_id": null,
        "idp_sso_url": null,
        "idp_slo_url": null,
        "certificate_fingerprints": [],
        "mfa_authn_context_values": null,
        "issuer": null,
        "client_id": null,
        "client_auth_method": null,
        "provider_profile": null,
        "client_secret_change": null
      },
      "latest_test": {
        "test_id": "conntest_01j9xr4a6b8c0d2e4f6g8h0j2k",
        "status": "passed",
        "failure_reason": null,
        "started_at": "2026-10-28T10:05:00Z",
        "completed_at": "2026-10-28T10:06:00Z"
      }
    }
  ],
  "list_metadata": { "before": null, "after": null }
}
```

| フィールド | 説明 |
|---|---|
| `kind` | `configuration`（ID プロバイダまたは OIDC クライアントの変更）または `sp_host`（SP ホストの移行）。 |
| `status` | `draft`（テストと公開を待機中）、`published`（公開済み）、または `discarded`（破棄済み）。 |
| `decided_at` / `purge_after` | リビジョンが公開または破棄された日時、および削除される日時（90 日後）。ドラフトの場合は `null`。 |
| `changes` | 新しい値。リビジョンで変更されないフィールドは `null`。 |
| `latest_test` | このリビジョンの直近 24 時間以内の最新のテストサインイン、または `null`。公開には `passed` のテストが必要です。 |

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 400 | `invalid_cursor` | カーソルの形式が不正であるか、別の接続またはクエリに属しています。 |
| 401 | `unauthenticated` | 認証情報が存在しないか、無効または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に `connections:read` 権限がありません。 |
| 404 | `not_found` | 接続がこの環境に存在しないか、エンタープライズ接続ではありません。 |
| 422 | `validation_failed` | クエリパラメータが無効です（例: `limit` が 100 を超えている、または `before` を指定している）。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の期間を待ってから再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。`Retry-After` の期間を待ってから再試行してください。 |

## 例

```bash
curl "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/revisions?limit=20" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

```bash
keenauth connections revisions list conn_01j9xp6q0r1s5t7v9w1x3y5z7b --limit 20
```