API 키
API 키는 페이리 REST API를 호출할 때 쓰는 인증 수단이에요.
키는 스토어 단위로 발급되고, live(프로덕션)와 test(샌드박스) 두 모드가 있어요.
모든 요청은 X-Api-Key 헤더에 키 평문을 담아 보내요.
발급부터 인증까지
서버는 받은 키가 등록된 키인지 확인하고, 허용 IP와 요청에 필요한 스코프를 차례로 검사해요.
한 단계라도 통과하지 못하면 해당 에러로 응답해요.
키의 구성
| 항목 | 설명 |
|---|---|
| 종류 | secret(서버 전용, 기본) / browser(브라우저 노출용). 아래에서 다뤄요. |
| 모드 | live / test. 발급 후 변경 불가예요. |
| 평문 | pk_live_… / pk_test_…. 발급·회전 응답에만 1회 노출돼요. |
| 마스킹 | 이후엔 pk_live_••••3f9a처럼 끝 4자리만 보여요. |
| 스코프 | 이 키로 가능한 작업 범위예요. (스코프) |
| 허용 IP | 비어 있으면 모든 IP를 허용해요. (제한) |
| 상품 범위 | 키가 특정 상품만 다루도록 제한될 수 있어요. (제한) |
키 종류: secret / browser
| 종류 | 용도 | 스코프 |
|---|---|---|
secret (기본) | 서버→서버 호출 전용. 클라이언트에 노출하면 안 돼요 | 자유롭게 선택 |
browser | 구매자 브라우저에서 결제 세션 생성을 직접 호출할 때 | checkout:write 고정 |
browser 키는 브라우저 노출을 전제로 해요.
그래서 할 수 있는 일이 결제 세션 생성 하나로 고정되고, 발급 후에도 스코프를 바꿀 수 없어요.
조회·환불·해지 같은 나머지 작업은 전부 secret 키로만 가능해요.
browser 키는 구매자 브라우저에서 호출되므로 IP 제한도 두지 않아요.
평문 키는 발급 직후 단 한 번만 보여요.
페이리는 평문을 저장하지 않으므로 분실하면 복구할 수 없어요.
잃어버렸다면 키를 회전해 새 평문을 받으세요.
다음 단계
Last updated on