# 연결 테스트

`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`은 베어러 링크입니다. 이 URL을 가진 사람은 10분 이내에 한 번 테스트를 실행할 수 있습니다. 이 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분 동안 한 번만 유효합니다. 공유하거나 기록하지 마십시오. 재생된 응답에는 없습니다. |
| `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
```