Pactery API 인증 방법 | API 키와 Bearer 헤더

Pactery API는 조직에 발급된 API 키를 Authorization: Bearer {API_KEY} 헤더에 넣어 인증합니다. 키는 /app/settings/developer의 개발 설정에서 발급하며, 전체 키 문자열은 발급 직후 한 번만 보이므로 바로 안전한 곳에 저장해야 합니다.

API 키는 조직 단위로 동작합니다. 같은 사용자가 여러 워크스페이스를 쓰고 있다면, 어느 조직에서 발급한 키인지 먼저 확인해야 문서 생성, 발송, 조회 결과가 예상한 조직에 남습니다.

API 키를 발급하기 전에 확인할 것

API 키 발급과 폐기는 조직의 소유자 또는 관리자 권한에서 할 수 있습니다. 설정 화면에서 개발 메뉴로 들어가 키 이름을 정하고, 운영 키 또는 테스트 키를 선택해 발급합니다.

sk_live_로 시작하는 키는 운영용, sk_test_로 시작하는 키는 테스트용입니다. 운영 자동화에 붙일 키와 개발자가 로컬에서 실험할 키는 분리하는 편이 안전합니다. 키 이름도 백오피스 운영, 개발 테스트처럼 용도를 알 수 있게 적어 두면 나중에 폐기할 때 혼동이 줄어듭니다.

요청 헤더에 넣는 방식

모든 API 요청에는 Bearer 형식의 인증 헤더를 붙입니다. 문서를 생성하거나 상태를 조회하는 요청이라도 인증 헤더가 없거나 키 형식이 맞지 않으면 요청이 거절됩니다.

curl https://api.pactery.com/v1/documents \
  -H "Authorization: Bearer $PACTERY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-001"

기존 https://pactery.com/v1 경로도 호환되지만, 새 연동에서는 API 전용 호스트인 https://api.pactery.com/v1을 기준으로 잡는 것이 정리하기 쉽습니다. POST 요청은 같은 작업이 중복 실행되지 않도록 Idempotency-Key도 함께 설계해 두세요.

키를 보관하고 폐기하는 기준

API 키는 프론트엔드 코드나 공개 저장소에 넣지 말고 서버 환경변수나 비밀 관리 도구에 보관합니다. 키가 노출되었거나 담당자가 바뀌었거나 더 이상 쓰지 않는 연동이라면 개발 설정 화면에서 해당 키를 폐기하세요. 폐기된 키로 들어오는 요청은 더 이상 통과하지 않습니다.

운영 서버에 배포하기 전에는 개발자 문서의 인증 예시와 OpenAPI JSON을 함께 확인해 요청 경로, 필수 헤더, 응답 오류 형식을 맞춰 두는 것이 좋습니다. 인증 오류가 난다면 키 접두사, 공백 포함 여부, 발급한 조직, 폐기 여부를 먼저 확인하세요.