# Postman 컬렉션과 OpenAPI 문서

KeenAuth는 기계가 읽을 수 있는 API 계약을 두 개의 파일로 게시합니다. 두 파일은 모든 릴리스마다 공개 관리 API 정의에서 생성되므로 항상 API 레퍼런스와 일치합니다. 내부 작업은 이 파일들에 포함되지 않습니다.

| 파일 | 형식 | 다운로드 |
|---|---|---|
| Postman 컬렉션 | Postman Collection v2.1.0 | [postman_collection.json](/api/postman_collection.json) |
| OpenAPI 문서 | OpenAPI 3.1 | [openapi.json](/api/openapi.json) |

## Postman으로 가져오기

1. Postman에서 **Import**를 선택하고 다운로드한 `postman_collection.json`을 선택하십시오.
2. 컬렉션 변수를 열고 `apiKey`를 관리 API 키로 설정하십시오. 키는 대시보드 또는 CLI에서 만들 수 있습니다. 이 키는 Bearer 토큰으로 전송됩니다.
3. `region`을 환경의 리전으로 설정하십시오. 기본값은 `eu`입니다. 요청은 호스트 `api.{{region}}.keenauth.com`, 경로 `/v1`로 전송됩니다.
4. 요청을 보내십시오. 모든 `POST` 요청에는 Postman이 새 GUID로 채우는 `Idempotency-Key` 헤더가 포함되므로 재시도한 요청도 안전합니다.

요청은 API 태그마다 하나의 폴더로 묶여 있습니다. `{{user_id}}` 같은 경로 매개변수는 컬렉션 변수입니다. 해당 변수가 필요한 요청을 보내기 전에 값을 설정하십시오.

## OpenAPI 문서 사용하기

OpenAPI 문서는 코드 생성과 API 게이트웨이, 린터, 목 서버의 입력으로 사용됩니다. 같은 문서는 API 자체에서도 `https://api.eu.keenauth.com/v1/openapi.json`으로 제공됩니다.

## 계약 아카이브와 SDK 다이제스트

OpenAPI 문서는 콘텐츠 주소 기반 아카이브 경로에도 게시됩니다. 경로의 세그먼트는 문서 바이트의 SHA-256 값이므로 아카이브 경로의 파일은 변경되지 않습니다:

| 파일 | 내용 |
|---|---|
| `/openapi/<sha256>/openapi.json` | 문서입니다. 해당 버전의 `/api/openapi.json`과 바이트 단위로 동일합니다. |
| `/openapi/<sha256>/openapi.json.sha256` | `sha256sum` 형식의 다이제스트 |
| [`/openapi/index.json`](/openapi/index.json) | 아카이브된 문서: `sha256`, `info_version`, `path`. `current`는 최신 문서를 표시합니다. |

각 서버 SDK는 생성에 사용된 문서의 다이제스트를 기록합니다:

| SDK | 위치 |
|---|---|
| Node.js (`@keenauth/node`) | `OPENAPI_SHA256` 내보내기 및 `package.json`의 `keenauth.openapiSha256` |
| Python (`keenauth-python`) | `keenauth.OPENAPI_SHA256` 및 패키지 메타데이터의 `OpenAPI document` 프로젝트 URL |
| Go | `keenauth.OpenAPISHA256` |

다운로드한 파일을 확인하려면 두 파일이 들어 있는 폴더에서 `sha256sum -c openapi.json.sha256`을 실행하십시오. 다이제스트를 SDK가 보고한 값과 비교하여 SDK가 어떤 API 버전으로 빌드되었는지 확인하십시오.