연동 준비
API 키 발급
API 키는 개발자 콘솔에서 업체가 직접 발급하고 폐기합니다. 테스트 키와 운영 키가 따로 있으며, 키 전체 값은 발급 직후 한 번만 보여 줍니다.
키 종류 #
키 앞부분으로 모드를 구분합니다. 같은 API를 호출해도 어떤 키를 쓰느냐에 따라 테스트 데이터와 실데이터가 완전히 분리됩니다.
| 모드 | 용도 |
|---|---|
테스트 pl_test_… | 개발·검증용. 테스트 양도 코드를 만들어 확인 → 접수 → 승인 → 전달 링크까지 시험할 수 있습니다. 실재고·실거래와 무관합니다. |
운영 pl_live_… | 실제 거래용. 판매자가 넘겨준 실제 양도 코드를 접수하고, 구매자에게 실제 상품권 PIN을 전달 링크로 보여 줍니다. |
발급하기 #
콘솔의 API 키 메뉴 열기
업체 승인을 받은 계정으로 로그인한 뒤 개발자 콘솔의 API 키 메뉴로 갑니다.
모드와 이름을 정해 발급
테스트·운영 중 하나를 고르고 키 이름(1~40자)을 붙입니다. 이름은 어느 서버·용도에서 쓰는 키인지 알아볼 수 있게 정하세요. 예: 양도서버-운영
키 전체 값을 바로 복사해 보관
발급 직후 화면에 키 전체 값이 한 번만 표시됩니다. 창을 닫으면 다시 볼 수 없으니 바로 서버의 비밀 저장소나 환경변수에 넣으세요.
환경변수 예시
# .env (서버 전용, 저장소에 커밋하지 마세요)
PINLOCK_API_KEY=pl_live_여기에_발급받은_키키 전체 값은 다시 볼 수 없습니다
핀락 서버에는 키의 SHA-256 해시만 저장되므로 핀락도 원래 값을 알려 드릴 수 없습니다. 잃어버렸다면 새 키를 발급하고 이전 키를 폐기하세요.
키 목록에서 보이는 것 #
- 앞 12자리(prefix): 어떤 키인지 구분하는 용도입니다. 예:
pl_live_ab12 - 마지막 사용 시각: 교체할 때 이전 키가 더 이상 쓰이지 않는지 확인하는 데 씁니다.
- 모드별로 활성 키는 최대 5개까지 둘 수 있습니다. 더 필요하면 쓰지 않는 키를 폐기하세요.
보관 규칙 #
- 키는 서버 환경변수나 비밀 저장소에만 둡니다.
- 코드 저장소, 브라우저 코드, 모바일 앱, 로그, 메신저에 남기지 마세요. 브라우저·앱에서 핀락 API를 직접 호출하면 키가 노출됩니다.
- 테스트 키와 운영 키를 다른 변수·다른 환경에 두어 섞이지 않게 하세요.
폐기 #
콘솔 API 키 목록에서 폐기하면 즉시 효력을 잃고, 그 키로 보낸 요청은 바로 401 UNAUTHORIZED 를 받습니다. 폐기는 되돌릴 수 없습니다.
키가 유출되었다면
바로 해당 키를 폐기하고 새 키를 발급해 서버에 반영하세요. 폐기가 먼저입니다. 새 키를 배포하는 동안 잠시 요청이 실패하더라도 유출된 키가 쓰이는 것보다 안전합니다.
교체(로테이션) 절차 #
정기 교체나 담당자 변경 등으로 키를 바꿀 때는 중단 없이 아래 순서로 진행하세요.
- 같은 모드로 새 키를 발급합니다. 활성 키가 이미 5개라면 쓰지 않는 키부터 폐기하세요.
- 새 키를 서버에 배포하고, 요청이 정상인지
GET /v1/me등으로 확인합니다. - 콘솔에서 이전 키의 마지막 사용 시각이 더 이상 갱신되지 않는지 확인합니다.
- 이전 키를 폐기합니다.