# 接続をテスト

`POST /v1/connections/{connection_id}:test` · 権限 `connections:write`

エンタープライズ接続の現在の設定でテストサインインを開始し、テスト URL を返します。接続を設定する担当者は、その URL をブラウザで開き、ID プロバイダでサインインします。ブラウザは、`test_id` クエリパラメータを付けて `return_url` に戻ります。結果は[最新のテスト結果を取得](latest-test-result.md)で確認してください。

テストサインインでは、セッションは作成されず、ユーザーのプロビジョニングも、アカウントのリンクも行われません。接続を有効化するには、テストに合格している必要があります。ID プロバイダの設定を変更すると、そのテスト結果は無効になります。

公開中の設定ではなく[下書きのリビジョン](revisions.md)をテストする場合は、その `revision_id` を送信してください。下書きは、このテストに限り公開中の設定に重ねて適用されます（SP ホストの移行の場合、テスト URL は新しいホストになります）。リビジョンのテストに合格すると、[リビジョンを公開](publish-revision.md)するために必要な根拠になります。ただし、公開中の設定に対する有効化の根拠にはなりません。

`test_url` はベアラーリンクです。これを持つ人は、10 分以内に 1 回だけテストを実行できます。この URL は、このレスポンスでのみ返され（`Cache-Control: no-store`）、ログや監査には記録されません。同じ `Idempotency-Key` でリクエストを繰り返した場合、再生されたレスポンスには `test_url` が含まれず、`secret_redacted: true` が設定されます。その場合は、新しくテストを開始してください。テストの開始は、テスト ID のみを含めて `connection.test_started` として監査されます。

## リクエスト

| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| `connection_id` | path | はい | エンタープライズ接続 ID（`conn_…`）。 |
| `return_url` | string | はい | テスト後にブラウザが戻る絶対 `https` URL。2048 バイト以内。`test_id` がクエリパラメータとして追加されます。 |
| `revision_id` | string | いいえ | 公開中の設定ではなくテストする、接続の下書きリビジョン（`connrev_…`）。 |

## レスポンス

`200 OK`:

```json
{
  "test_id": "conntest_01j9xr4a6b8c0d2e4f6g8h0j2k",
  "test_url": "https://acme.eu1.keenauth.app/sso/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/start?t=…",
  "expires_at": "2026-10-20T10:10:00Z"
}
```

| フィールド | 説明 |
|---|---|
| `test_id` | テスト ID（`conntest_…`）。 |
| `test_url` | ブラウザで開く URL。有効期間は 10 分間、1 回のみ使用できます。共有もログ記録もしないでください。再生されたレスポンスには含まれません。 |
| `expires_at` | テスト URL の有効期限。 |
| `secret_redacted` | 同じ `Idempotency-Key` で再生されたレスポンスの場合は `true`。 |

## エラー

| HTTP | code | 発生条件 |
|---|---|---|
| 404 | `not_found` | この環境に接続が存在しないか、エンタープライズ接続ではありません。 |
| 409 | `conflict` | 接続はまだテストできません（プロトコル設定がありません）。 |
| 422 | `validation_failed` | `return_url` がない、または絶対 `https` URL ではありません（`errors[]` は `/return_url` を指します）。または `revision_id` の形式が不正（`invalid_value`）、またはこの接続の下書きリビジョンではありません（`not_found`、ポインタは `/revision_id`）。 |
| 400 | `unknown_field` | リクエストボディに未知のフィールドが含まれています。 |
| 401 | `unauthenticated` | 認証情報がない、無効である、または取り消されています。 |
| 403 | `insufficient_permissions` | 認証情報に必要な権限がありません。 |
| 429 | `rate_limited` | レート制限を超えました。`Retry-After` の期間を経過してから再試行してください。 |
| 503 | `service_unavailable` | 依存先が一時的に利用できません。`Retry-After` の期間を経過してから再試行してください。 |

## 例

```bash
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b:test" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"return_url":"https://admin.example.com/sso/test-done"}'
```

```bash
keenauth connections test conn_01j9xp6q0r1s5t7v9w1x3y5z7b --return-url https://admin.example.com/sso/test-done
```