리셀러 API 는 전체 권한(supervisor) 키 대신, 필요한 API 만 허용한 범위 키로도 호출할 수 있다. 키에 그 API 의
reseller:*스코프가 있어야 한다.
핵심 요약
- Basic Auth 의 리셀러 키가 전체 권한(supervisor) 키면 지금처럼 모든 리셀러 API 를 부를 수 있다.
- 전체 권한이 아닌 키(범위 키)는 아래 표에서 그 API 의 스코프를 받은 경우에만 부를 수 있다. 없으면
API_SCOPE_INVALID(HTTP 401). - 스코프는 API 묶음 단위다. 예를 들어
reseller:seller:read만 받은 키는 가맹점 목록·조회만 되고 가맹점 생성은 막힌다. - 테스트 데이터 삭제(
DELETE /v2/reseller/test/seller/:provider_id)는 스코프가 없다 — 전체 권한 키로만 부른다. - 결제 조회용 등 다른 용도로 만든 범위 키로는 리셀러 API 를 부를 수 없다. 리셀러 연동 서버용 키를 따로 만든다.
- Bearer 토큰(
Application ID+Private Key로 받은 레거시 토큰)은 이 검사를 받지 않는다.
스코프 목록
| 스코프 | 허용하는 API | 문서 |
|---|---|---|
reseller:seller:read |
GET /v2/reseller/seller · GET /v2/reseller/seller/:provider_id · GET /v2/reseller/me · GET /v2/reseller/billing |
가맹점 목록 · 가맹점 조회 · 리셀러 내 정보 · 알림톡 이용료 대납 |
reseller:seller:write |
POST /v2/reseller/seller · PUT /v2/reseller/seller/:provider_id |
가맹점 생성 · 가맹점 정보 수정 |
reseller:app:read |
GET /v2/reseller/seller/app · GET /v2/reseller/seller/app/:app_id · GET /v2/reseller/seller/app/:app_id/payment-methods · GET /v2/reseller/pgs · GET /v2/reseller/seller/app/commerce/:app_id/webhook |
프로젝트 목록 · 프로젝트 조회 · 결제수단 목록 · PG·필수 연동 값 목록 · 커머스 웹훅 설정 |
reseller:app:write |
POST /v2/reseller/seller/app · PATCH /v2/reseller/seller/app/resource/:app_id · PUT /v2/reseller/seller/app/commerce/:app_id · PUT /v2/reseller/seller/app/commerce/:app_id/webhook · POST /v2/reseller/alimtalk/channel/link · PUT /v2/reseller/seller/app/:app_id/payment-lock |
프로젝트 생성 · PG 리소스 갱신 · 커머스 연동 재시도 · 커머스 웹훅 설정 · 알림톡 채널 일괄 연결 · 결제 설정 잠금 |
reseller:key:read |
GET /v2/reseller/seller/app/key-chain/:app_id · GET /v2/reseller/scopes |
키 생성·조회 · 키 발급 스코프 목록 |
reseller:key:write |
POST /v2/reseller/seller/app/key-chain · DELETE /v2/reseller/seller/app/key-chain/:key_chain_id · POST /v2/reseller/seller/app/keys/reissue |
키 생성·조회 · 키 재발급 |
reseller:onboarding:read |
GET /v2/reseller/seller/:provider_id/onboarding · GET /v2/reseller/seller/:provider_id/onboarding/:onboarding_id/documents · GET /v2/reseller/agreements |
등록 상태 조회 · 신청서 서류 열기 · 등록 API 접수 |
reseller:onboarding:write |
POST /v2/reseller/seller/:provider_id/onboarding/session · POST /v2/reseller/seller/:provider_id/onboarding · PUT /v2/reseller/seller/:provider_id/onboarding/:onboarding_id · POST /v2/reseller/seller/:provider_id/files/grant |
등록 폼 세션 발급 · 등록 API 접수 |
reseller:webhook:read |
GET /v2/reseller/webhook |
리셀러 웹훅 |
reseller:webhook:write |
PUT /v2/reseller/webhook |
리셀러 웹훅 |
reseller:invite:write |
POST /v2/reseller/invite |
프로젝트 초대 |
*:write 스코프는 같은 묶음의 *:read 를 포함하지 않는다. 조회도 하려면 두 스코프를 함께 준다.
범위 키 만드는 법
리셀러 계정으로 관리자 콘솔 → 개발자 설정 > 결제 연동키 에서 리셀러 프로젝트의 새 키를 발급하고, 권한 범위(Scope) 에서 리셀러 그룹의 필요한 스코프만 고른다. 화면 사용법은 연동키 발급 과 같다.
호출 방법은 전체 권한 키와 같다.
Authorization: Basic base64(client_key:secret_key)나눠 쓰는 예
- 가맹점 가입을 받는 서버:
reseller:seller:write·reseller:app:write·reseller:onboarding:write - 대시보드처럼 읽기만 하는 서버:
reseller:seller:read·reseller:app:read·reseller:onboarding:read - 키 발급·재발급은 따로 둔 관리 서버 키에만
reseller:key:write
API 권한과는 별개
범위 키 검사를 통과해도, 부트페이가 리셀러 계정에 열어 둔 API 권한이 꺼져 있으면 쓰기 API 는 막힌다. 두 검사를 모두 통과해야 한다.
오류 코드
| 코드 | 메시지 | 대처 방법 |
|---|---|---|
API_SCOPE_INVALID |
키에 이 API 의 스코프가 없다 (HTTP 401) | 위 표에서 그 API 의 스코프를 키에 추가하거나 전체 권한 키로 호출한다. 테스트 데이터 삭제는 전체 권한 키만 된다 |
API_ROLE_NOT_SUPPORT |
이 API 의 스코프가 아직 준비되지 않았다 (HTTP 401) | 전체 권한 키로 호출하고 부트페이에 문의한다 |
APP_KEY_CHAIN_EXPIRED |
키가 만료됐다 (HTTP 401) | 만료일을 확인하고 새 키를 발급한다 |
