v1 API 는 프로젝트 인증(어느 쇼핑몰의 요청인가)과, 필요한 경우 회원 인증(어느 구매자의 요청인가)을 따로 받습니다. 이 문서는 프로젝트 인증을 다룹니다. 회원 인증은 회원 JWT를 봅니다.
호출 구조 — 쇼핑몰 서버를 거친다
쇼핑몰 기능(회원·마이페이지·주문·취소·장바구니 등)은 다음 3단계로 구현합니다.
브라우저(프론트엔드) → 쇼핑몰 서버(Next.js Route Handler·Server Action, Nuxt server route 등) → Bootpay commerce v1- secretKey 는 쇼핑몰 서버에만 둡니다. 브라우저가 v1 을 직접 부르지 않습니다.
- 회원을 지정하는 API 는 쇼핑몰 서버가 자기 로그인 세션에서 꺼낸 회원 값을 넣습니다. 회원을 정하는 방법은 API 마다 다르며 각 문서의 인증 절에 적혀 있습니다.
- 회원 JWT(
Bootpay-User-JWT)를 받는 API: 로그인 때 받은 JWT 를 서버 세션에 보관했다가 넣습니다. 회원 JWT user_id로 회원을 받는 API:user_id를 넣습니다. 24자리 회원 ID 형식이면 Bootpay 회원 ID 로, 그 밖의 값은 이 몰의 외부 회원 ID(ex_uid)로 찾습니다.user_ex_uid·user_external_uid·user_uid도 같은 뜻으로 받습니다. 로그인 아이디로 지정하려면user_id대신login_id를 보냅니다(user_id와 함께 보내면 같은 회원이어야 하며, 다르면 403USER_NOT_MATCH). 이 몰의 회원이 아니거나 탈퇴한 회원이면 404USER_NOT_FOUND입니다.- 인증 절에 JWT 또는 user_id 로 적힌 API 는 둘 중 하나만 보내면 됩니다. 둘 다 보내면 JWT 가 우선이고, 서로 다른 회원이면 403
USER_NOT_MATCH입니다.user_id는 secretKey 인증(Basic·Bearer)일 때만 받습니다 — clientKey 만으로 부른 요청에user_id를 넣으면 400API_PARAM_INVALID입니다.
- 회원 JWT(
- 브라우저가 보낸
user_id·주문번호를 그대로 넘기지 않습니다. 가맹점 권한 API 는 이 몰의 모든 회원·주문을 다룰 수 있으므로, 로그인한 회원의 것인지 확인하는 책임은 쇼핑몰 서버에 있습니다.
Basic 인증 (기본)
Authorization: Basic base64(clientKey:secretKey)clientKey·secretKey는 부트페이 관리자 [연동키 및 보안] 에서 발급한 키입니다.clientKey:secretKey문자열을 Base64 로 인코딩해Basic뒤에 붙입니다.- 키는 서버에만 두세요. 브라우저·앱에 secretKey 를 넣으면 누구나 이 쇼핑몰의 API 를 호출할 수 있습니다.
curl https://api.bootapi.com/v1/products \
-H "Authorization: Basic $(printf '%s:%s' "$CLIENT_KEY" "$SECRET_KEY" | base64)"bashBearer 토큰 (레거시)
Authorization: Bearer <access_token>POST /v1/request/token 으로 받은 토큰입니다. 기존 연동 호환용으로만 남아 있으며 신규 연동에는 쓰지 않습니다.
API 권한(scope)
키마다 호출할 수 있는 API 범위(scope)가 부여됩니다. scope 는 <역할>:<이름> 형식입니다(예: user:product_list).
- 역할은
Bootpay-Role헤더로 고릅니다. 보내지 않으면user입니다. - 각 엔드포인트 문서의 인증 절에 필요한 scope 가 적혀 있습니다.
- 권한이 없는 키로 호출하면
401 API_SCOPE_INVALID가 옵니다. 관리자에서 키에 권한을 추가하거나 권한이 포함된 새 키를 발급받으세요.
IP 보안
관리자에서 허용 IP 를 설정했다면 등록되지 않은 IP 의 호출은 401 PROJECT_FIREWALL_BLOCKED 로 거절됩니다. 서버 IP 가 바뀌면 관리자 설정도 함께 바꾸세요.
인증 오류
| HTTP | error_code | 언제 |
|---|---|---|
| 400 | TOKEN_AUTHORIZE_TYPE_INVALID |
Authorization 이 Basic/Bearer 로 시작하지 않거나 헤더가 없음 |
| 400 | PROJECT_AT_AUTHORIZE_BASIC_INVALID |
Basic 값에서 clientKey 또는 secretKey 를 읽을 수 없음 |
| 404 | PROJECT_SERVER_KEY_INVALID |
없는 clientKey |
| 401 | PROJECT_PK_INVALID |
secretKey 불일치 |
| 401 | PROJECT_CLIENT_KEY_EXPIRED |
만료된 clientKey |
| 401 | PROJECT_CLIENT_KEY_REVOKED |
관리자에서 삭제한 clientKey, 또는 삭제 뒤 그 키로 받은 토큰(Bearer) |
| 401 | PROJECT_NOT_ALLOW |
이용이 중지된 프로젝트 |
| 401 | SELLER_NOT_ALLOW |
이용이 중지된 판매자 계정 |
| 401 | PROJECT_FIREWALL_BLOCKED |
허용되지 않은 IP |
| 401 | API_SCOPE_INVALID |
키에 필요한 scope 가 없음 |
| 404 | TOKEN_NOT_FOUND |
(Bearer) 잘못되었거나 만료된 토큰 |
응답 형식은 오류를 봅니다.

