인증

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 와 함께 보내면 같은 회원이어야 하며, 다르면 403 USER_NOT_MATCH). 이 몰의 회원이 아니거나 탈퇴한 회원이면 404 USER_NOT_FOUND 입니다.
    • 인증 절에 JWT 또는 user_id 로 적힌 API 는 둘 중 하나만 보내면 됩니다. 둘 다 보내면 JWT 가 우선이고, 서로 다른 회원이면 403 USER_NOT_MATCH 입니다. user_id 는 secretKey 인증(Basic·Bearer)일 때만 받습니다 — clientKey 만으로 부른 요청에 user_id 를 넣으면 400 API_PARAM_INVALID 입니다.
  • 브라우저가 보낸 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)"bash

Bearer 토큰 (레거시)

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) 잘못되었거나 만료된 토큰

응답 형식은 오류를 봅니다.

함께 보기