서버 인증

커머스 API는 별도의 토큰 발급 없이 Basic 인증만으로 바로 호출​​할 수 있어요. 매뉴얼의 모든 API 문서가 엔드포인트 블록에 Basic Auth 로만 표기된 것은 그래서예요. 액세스 토큰은 매 요청 인증을 줄이고 싶을 때 꺼내 쓰는 선택지고, 구독 승인·해지나 금액 조정처럼 되돌리기 어려운 운영 API 에는 supervisor 권한이 한 겹 더 붙어요.

• 커머스 API는 Basic 인증만으로 바로 호출​​할 수 있어요. 매뉴얼의 모든 API 문서가 Basic Auth 로 표기된 이유예요.
• Bearer 액세스 토큰은 기존 연동 호환용​​이에요. 신규 연동은 Basic 인증을 사용해요.
• 구매자 본인 API 는 프로젝트 인증에 더해 Bootpay-User-JWT 또는 엔드포인트가 허용하는 user_id 가 필요해요.
• 키와 토큰은 모두 서버 전용 자산으로 다루고, 프론트엔드에는 절대 노출하지 않아요.
• 일부 운영 API는 supervisor 권한​​이 필요해요. 권한은 토큰이 아니라 API 연동키에 설정해요.

이런 상황이라면

상품 등록, 고객 생성, 주문 조회처럼 commerce 서버 API를 직접 호출해야 한다면 이 문서가 출발점이에요. 구독 승인·해지, 금액 조정처럼 supervisor 가 필요한 API 를 붙일 계획이라면 아래 5번을 먼저 봐요. 결제 SDK 인증을 이미 알고 있어도 키가 다르니 프로젝트와 탭을 다시 확인해요.

이 문서는 커머스 서버 호출에 필요한 최소 인증 흐름만 다뤄요.

1API 키 발급

commerce 인증은 먼저 대시보드에서 키를 확보하는 것부터 시작해요. 결제용 키와 커머스용 키를 헷갈리지 않도록 프로젝트와 탭을 정확히 확인해야 해요.

확인 위치:

• 관리자 콘솔
• 개발자 설정
• API 연동키
• commerce 키 영역

실무에서 먼저 확인할 항목은 다음과 같아요.

• 현재 프로젝트가 맞는가
• sandbox와 운영 환경을 구분했는가
• 서버에 저장할 client_key, secret_key가 commerce용인가

관련 문서:

• 환경 설정

결제 SDK의 서버 인증은 결제 매뉴얼: API 인증에서 확인해요.

2Basic 인증으로 바로 호출하기

커머스 API는 별도의 토큰 발급 없이 Authorization: Basic 헤더만으로 호출돼요. 커머스 client_key 와 secret_key 를 : 로 이어 Base64 로 인코딩해요.

Authorization: Basic {base64(client_key:secret_key)}

curl -X GET "https://api.bootapi.com/v1/products" \
  -H "Authorization: Basic $(printf '%s:%s' "$BOOTPAY_COMMERCE_CLIENT_KEY" "$BOOTPAY_COMMERCE_SECRET_KEY" | base64)"bash

3회원 인증과 서버 경계

브라우저는 자사 서버를 호출하고, 자사 서버가 프로젝트 키와 로그인 세션을 확인한 뒤 v1 API 를 호출해요. secret_key 는 서버의 비밀 저장소에, 회원 JWT 는 서버 세션에 보관해요. 브라우저가 보낸 user_id 나 주문번호를 검증 없이 가맹점 권한 API 에 전달하지 않아요.

• Bootpay-User-JWT 는 회원 로그인(POST /v1/users/login 또는 서버용 POST /v1/users/login/token)에서 받아요. 가입 API 는 JWT 를 발급하지 않으므로 가입 후 로그인해요.
• 엔드포인트가 JWT 또는 user_id 를 허용하면 둘 중 하나만 보내도 돼요. 둘 다 보내고 다른 회원을 가리키면 403 USER_NOT_MATCH 예요. user_id 는 secretKey 를 쓰는 가맹점 인증에서만 허용돼요.
• user_id 는 24자리 Bootpay 회원 ID 형식이면 회원 ID 로, 그 밖에는 해당 프로젝트의 외부 회원 ID(ex_uid)로 조회해요. user_ex_uid·user_external_uid·user_uid 도 같은 규칙이에요. 로그인 아이디는 login_id 로 보내요. 대상이 없거나 탈퇴했다면 404 USER_NOT_FOUND 예요.
• GET·DELETE /v1/users/session 은 JWT 세션 자체를 다루므로 JWT 전용이에요.

엔드포인트별 필수 여부와 선택 JWT 의 처리 방식은 회원 JWT를 확인해요.

4액세스 토큰 (기존 연동)

토큰을 쓰면 이후 요청에 키 대신 Authorization: Bearer {access_token} 을 보낼 수 있어요.

인증은 두 가지 방식 중 하나예요.

require 'bootpay'

commerce = BootpayStore::RestClient.new(client_key: '{client_key}', secret_key: '{secret_key}')
puts commerce.get_store   # 토큰 발급 없이 바로 호출돼요ruby

응답

{
  "access_token": "a3f1c0…",
  "expire_in": 1800
}json

기존 토큰 연동의 갱신

토큰 수명은 30분​​이에요. 같은 프로젝트로 다시 발급을 요청하면 유효한 토큰이 그대로 돌아오고, 만료 5분 전부터는 새 토큰​​이 발급돼요. 그래서 "만료 전 재발급"은 같은 엔드포인트를 다시 호출하는 것으로 끝나요.

갱신 설계 시 체크할 점:

• 여러 서버 인스턴스가 동시에 재발급할 때 충돌이 없는가
• 배치 작업 중 토큰 만료로 실패하지 않는가
• 장애 시 fallback으로 즉시 재발급이 가능한가

특히 상품 동기화나 주문 배치처럼 긴 작업이 있으면 선갱신이 더 안정적이에요.

5API 권한(scope)

API 연동키에는 <역할>:<이름> 형태의 scope 가 붙어요(예: user:product_list). 일부 운영 API 는 supervisor 역할의 scope 가 필요해요. 각 엔드포인트의 필요한 scope 는 v1 API 문서에 적혀 있어요.

권한은 호출할 때 만드는 값이 아니라 API 연동키에 미리 붙여 두는 값​​이에요.

curl -X PUT "https://api.bootapi.com/v1/order_subscriptions/{order_subscription_id}/approve" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Bootpay-Role: supervisor"bash

6API 문서와 공통 응답 규칙

v1 문서는 인증 없이 읽을 수 있어요. GET /v1/docs 는 색인, GET /v1/docs/<리소스> 는 리소스 문서예요. API 주소에 Accept: text/markdown 또는 Content-Type: text/markdown 을 보내면 실제 API 를 실행하지 않고 해당 문서를 돌려줘요. POST 에도 적용되므로 문서 확인 과정에서 주문이 생성되지 않아요.

curl -H 'Accept: text/markdown' https://api.bootapi.com/v1/products/example-idbash

웹 문서에서는 v1 API 색인부터 확인해요. 목록의 page·limit 규칙은 페이지네이션, 재시도 헤더는 멱등 키, 오류 본문과 442 상태는 오류 응답에 정리돼 있어요.

인증 오류

7보안 권장사항

키와 토큰은 모두 서버 비밀값으로 취급해요. 편의를 위해 프론트에 넣거나 브라우저 스토리지에 저장하면 인증 체계가 무너져요.

최소 권장사항은 다음과 같아요.

• client_key, secret_key는 환경 변수나 시크릿 매니저에 저장해요.
• 토큰 발급 로직은 백엔드에서만 실행해요.
• 토큰과 키를 로그에 그대로 남기지 않아요.
• sandbox와 운영 키를 분리해요.
• 주기적으로 키 관리 상태를 점검해요.

commerce는 상품과 주문 전체에 접근하므로 키 유출 영향이 결제 한 건보다 훨씬 넓어요. 그래서 인증을 단순 연결 코드가 아니라 운영 보안 범위로 봐야 해요.