# 연결에 IdP 서명 인증서 추가

`POST /v1/connections/{connection_id}/certificates` · 권한 `connections:write`

엔터프라이즈 SAML 연결에 IdP의 서명 인증서를 추가합니다. 인증서를 직접 업로드하거나 인증서를 교체(로테이션)할 때 사용합니다. 먼저 새 인증서를 추가하고, IdP를 새 인증서로 전환한 다음, 이전 인증서를 [삭제](delete.md)하세요. 교체는 활성 연결에서도 즉시 적용됩니다.

인증서는 하나의 PEM `CERTIFICATE` 블록(최대 8 KiB)이어야 합니다. 만료되지 않아야 하며, 2048비트 이상의 RSA 키 또는 ECDSA P-256, P-384, P-521 키를 가져야 합니다. 거부되면 응답은 이유를 알려 주지 않으며, 이유와 인증서 내용은 기록되지 않습니다. 연결당 활성 인증서는 최대 3개입니다. 연결에서 삭제된 인증서는 다시 추가할 수 없습니다. 이 요청은 `If-Match` 헤더를 받지 않습니다. 쓰기 작업은 `connection.idp_certificate_added`로 감사됩니다.

## 요청

| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
| `connection_id` | 경로 | 예 | 엔터프라이즈 SAML 연결 ID(`conn_…`). |
| `certificate` | 문자열 | 예 | PEM 인증서 하나(`-----BEGIN CERTIFICATE-----` …), 최대 8 KiB. |

## 응답

새 인증서와 함께 `201 Created`를 반환합니다([인증서 목록](list.md) 참고). 같은 인증서가 이미 연결에 있으면 등록된 인증서와 함께 `200 OK`를 반환하며, 아무것도 기록되거나 감사되지 않습니다.

```json
{"id": "conncert_01j9xq2m4n6p8r0s2t4v6w8y0a", "sha256_fingerprint": "3b0c…", "not_before": "2026-01-01T00:00:00Z", "not_after": "2028-01-01T00:00:00Z", "source": "manual"}
```

## 오류

| HTTP | code | 발생 조건 |
|---|---|---|
| 404 | `not_found` | 이 환경에 연결이 없거나 엔터프라이즈 SAML 연결이 아닙니다. |
| 409 | `conflict` | 연결이 SAML 연결이 아니거나, SAML 설정이 아직 없거나, 활성 인증서가 이미 3개이거나, 이 인증서가 전에 연결에서 삭제되었습니다. |
| 422 | `validation_failed` | 인증서가 없거나, 너무 크거나, 허용되지 않습니다. `errors[]`가 `/certificate`를 가리킵니다. 스테이징 및 운영 환경은 [로컬 모의 서버](/docs/cli/mock-server)의 공개 테스트 키에 해당하는 인증서도 거부합니다. |
| 400 | `unknown_field` | 본문에 알 수 없는 필드가 있습니다. |
| 401 | `unauthenticated` | 자격 증명이 없거나, 잘못되었거나, 취소되었습니다. |
| 403 | `insufficient_permissions` | 자격 증명에 필요한 권한이 없습니다. |
| 429 | `rate_limited` | 요청 한도를 초과했습니다. `Retry-After` 기간이 지난 후 다시 시도하세요. |
| 503 | `service_unavailable` | 종속 서비스를 일시적으로 사용할 수 없습니다. `Retry-After` 기간이 지난 후 다시 시도하세요. |

## 예시

```bash
jq -Rs '{certificate: .}' idp-signing.pem > cert.json
curl -X POST "https://api.eu.keenauth.com/v1/connections/conn_01j9xp6q0r1s5t7v9w1x3y5z7b/certificates" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d @cert.json
```

```bash
keenauth connections certificates add conn_01j9xp6q0r1s5t7v9w1x3y5z7b --certificate-file idp-signing.pem
```