# API 버전 관리 및 지원 중단 정책

이 페이지는 KeenAuth가 API의 버전을 관리하는 방식, 제거를 공지하는 방식, 그리고 SDK, CLI, Terraform/OpenTofu 프로바이더 및 MCP 서버가 보안 수정을 받는 기간을 설명합니다. 모든 공지는 [변경 로그](/docs/changelog)에 게시됩니다.

## API 버전

관리 API는 경로에 주 버전(`/v1`)을 포함합니다. `v1` 안에서는 추가적인 변경만 이루어집니다.

- 새 엔드포인트
- 새 선택적 요청 필드
- 새 응답 필드
- 새 enum 값
- 새 오류 코드
- 새 이벤트 유형

이러한 추가를 받아들일 수 있도록 통합을 작성하세요.

호환성을 깨는 변경은 새 주 버전(`/v2`)에서만 이루어집니다. 호환성을 깨는 변경은 필드 제거 또는 이름 변경, 유형 변경, 필수 필드 추가, 기본 동작 변경, 그리고 페이지 매기기, 정렬 또는 기본 `limit` 값 변경입니다. `v1`은 `v2`가 정식 출시된 후 최소 24개월 동안 계속 사용할 수 있습니다.

KeenAuth는 날짜 기반 버전 헤더를 사용하지 않습니다. 경로의 주 버전과 추가 변경만 허용하는 규칙이 계약의 전부입니다.

### 베타 및 GA 작업

OpenAPI 문서에서 모든 작업은 `x-idp-stability: beta` 또는 `x-idp-stability: ga`로 표시됩니다. `beta` 작업은 비공개 또는 공개 베타 기간에 변경될 수 있으며 아래의 지원 중단 규칙이 적용되지 않습니다. 이 작업의 응답에는 `Idp-Stability: beta` 헤더가 포함됩니다. `ga` 작업은 고정되며 이 페이지의 규칙에 따라서만 변경됩니다.

### 이벤트 및 토큰 클레임

- 고객 이벤트 유형에는 스키마 버전(`v<n>`)이 있습니다. 페이로드의 호환성을 깨는 변경은 새 스키마 버전을 만듭니다. 두 버전은 365일 동안 병행 전달되며 각 웹훅 엔드포인트가 받을 버전을 선택합니다.
- 토큰 클레임 추가는 추가적인 변경입니다. 클레임을 제거하거나 의미를 바꾸는 경우 365일 전에 공지하며 디스커버리 문서의 `claims_supported`를 업데이트합니다.

## 지원 중단 및 제거

엔드포인트, 매개변수, 클레임, scope, 이벤트 유형, 서명 알고리즘 또는 기타 대상의 제거는 제거일 최소 365일 전에 변경 로그에 공지됩니다. 모든 지원 중단에는 `dep-<YYYY>-<NN>` 형식의 식별자, 지원 중단일, 제거일(sunset), 대체 항목(있는 경우) 및 마이그레이션 가이드가 있습니다.

**보안 예외:** 보안 취약점을 해결하기 위해 `v1` 안의 동작이 365일 사전 공지 없이 변경될 수 있습니다. 이러한 변경은 변경 로그에 `security` 태그와 함께 게시되며 영향을 받는 환경에는 이메일로 알립니다.

### API 응답의 신호

제거 예정인 작업의 응답에는 다음이 포함됩니다.

- `Deprecation: @<unix_epoch>`: RFC 9745 구조화 날짜 형식의 지원 중단일
- `Sunset: <IMF-fixdate>`: 제거일(RFC 8594)
- `Link: <doc_url>; rel="deprecation"` 및 `Link: <doc_url>; rel="sunset"`: 마이그레이션 가이드

제거일 이후 해당 작업은 문제 코드 `endpoint_sunset`과 함께 `410`으로 응답합니다. OAuth 및 OpenID Connect 프로토콜의 제거(서명 알고리즘, 클라이언트 인증 방식, 매개변수)는 헤더를 전달할 수 없으므로 클라이언트별로 집계되며 같은 알림 경로를 거칩니다.

### 사용량을 확인하는 곳

- **환경 로그:** 시간당 최대 한 번 기록되는 `deprecation_notice` 레코드(`deprecation_id`, `client_id`, `sunset_at` 포함)
- **대시보드:** 지원 중단 페이지에서 최근 30일을 지원 중단, 클라이언트 및 SDK 버전별로 보여 줍니다. 제거일 90일 전부터 배너가 표시됩니다.
- **API:** `GET /v1/reports/deprecation-usage?from=&to=`(권한 `reports:read`)
- **이메일:** 계정의 `owner` 및 `admin` 역할과 환경의 기술 담당자에게 공지 당일(해당 대상을 사용하는 모든 환경)과 제거일 180일, 90일, 30일, 7일 전(최근 30일 동안 사용한 환경)에 발송됩니다.

공식 SDK, CLI, 프로바이더 및 MCP 서버는 모든 요청에 `Idp-Client: <package>/<version> (<runtime>/<version>)`를 보냅니다. 이 헤더는 인증 수단이 아니며 집계에만 사용되고, 형식에 맞지 않는 값은 무시됩니다. 사용량 집계에는 IP 주소, `User-Agent` 또는 최종 사용자 식별자가 저장되지 않습니다.

## SDK 및 도구 지원 정책

SDK, CLI, Terraform/OpenTofu 프로바이더 및 MCP 서버는 유의적 버전(semver)을 따릅니다. 주 버전은 언어 자체의 호환성을 깨는 변경이 있거나 API의 새 주 버전이 나올 때만 올라갑니다.

- 제품군 전체는 정식 출시일로부터 최소 5년간 보안 지원을 받습니다.
- 보안 수정은 각 패키지의 최신 주 버전으로 릴리스되며 해당 버전으로의 업그레이드는 무료입니다.
- 이전 주 버전은 새 주 버전이 정식 출시된 후 12개월 동안 보안 수정과 중대한 버그 수정을 받으며, 그 후 지원이 종료됩니다.
- 게시된 모든 보안 업데이트는 최소 10년 동안, 또는 남은 지원 기간이 더 길면 그 기간 동안 계속 제공됩니다.
- 지원 종료 90일 전부터 SDK는 서버의 `Deprecation` 헤더와 자체 지원 종료일을 애플리케이션 로그에 경고로 기록합니다.
- 지원이 종료된 SDK 버전은 서버에서 차단되지 않으며 대시보드와 이메일로 경고합니다.
- 지원 종료는 변경 로그와 패키지 레지스트리에 공지됩니다(npm `deprecate`, PyPI에서는 설명으로 알리며 릴리스를 철회하지 않음).

### 런타임 지원

SDK는 각 공급업체가 아직 보안 수정을 제공하는 런타임 버전을 지원합니다. Node.js LTS, 업스트림 지원 일정에 따른 Python, Go의 최근 두 릴리스, Java 17 및 21, .NET LTS, PHP 8.2 이상, Ruby 3.2 이상, iOS 16 이상, Android API 26 이상입니다. 최소 런타임 매트릭스는 주 버전마다 게시됩니다. 공급업체 지원이 끝난 런타임은 부 버전에서 제외되며, 90일 전에 변경 로그에 공지됩니다.