서버 인증 | Bootpay 커머스 매뉴얼

서버 토큰 발급부터 Commerce API 호출까지 인증 흐름을 고정해요.

핵심 요약

커머스 API는 서버에서 발급한 인증 토큰으로 호출해요.
먼저 대시보드에서 커머스용 API 키를 발급하고, 토큰 엔드포인트에서 access token을 받아 사용해요.
토큰은 만료 전 갱신 전략을 가져가야 상품·주문·고객 API 호출이 끊기지 않아요.
키와 토큰은 모두 서버 전용 자산으로 다루고, 프론트엔드에는 절대 노출하지 않아요.

이런 상황이라면

상품 등록, 고객 생성, 주문 조회처럼 commerce 서버 API를 직접 호출해야 한다면 이 인증 흐름이 필요해요. 결제 SDK만 붙이는 것이 아니라 catalog, customer, orders, subscription API를 함께 쓴다면 토큰 관리가 필수예요. 이미 결제 SDK 인증 흐름을 알고 있어도 커머스는 별도 토큰 발급 과정을 거치므로 다시 구분해서 봐야 해요.

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

1API 키 발급

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

확인 위치:

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

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

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

2토큰 발급 엔드포인트

commerce는 키를 그대로 매 요청에 보내지 않고, 먼저 토큰 엔드포인트에서 access token을 발급받아 사용해요.

기본 엔드포인트는 아래와 같아요.

POST https://api.bootapi.com/v1/token

요청 바디에는 commerce client_key와 secret_key를 담아요.

{
  "client_key": "COMMERCE_CLIENT_KEY",
  "secret_key": "COMMERCE_SECRET_KEY"
}json

응답으로 받은 access token은 이후 catalog, customer, orders, subscription API 호출에 붙여요.

이 단계에서 흔한 실수는 다음과 같아요.

결제 SDK 키를 넣어요.
프론트엔드에서 토큰 발급을 시도해요.
발급 받은 토큰을 너무 오래 재사용해요.

상품 중심으로 보면 토큰을 쓰는 대표 API는 다음과 같아요.

상품 생성과 수정
고객 등록과 조회
주문 조회와 취소
구독 관리

3토큰 갱신

토큰은 발급하고 끝나는 값이 아니에요. 만료되기 전에 다시 발급하는 전략이 있어야 서버 작업이 안정적이에요.

가장 단순한 운영 방식은 두 가지예요.

방식	설명	적합한 경우
요청 실패 시 재발급	401 또는 인증 실패 시 새 토큰 발급	초기 연동, 저트래픽
만료 전 선갱신	서버 메모리나 캐시에 만료 시점을 저장하고 미리 재발급	운영 서비스, 배치 작업

갱신 설계 시 체크할 점:

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

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

4보안 권장사항

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

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

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

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

다음 단계

환경 설정에서 commerce 키를 다시 확인해요.
상품부터 시작한다면 카탈로그 이해하기로 이동해요.
주문 흐름을 붙일 계획이면 체크아웃 이해하기와 주문 이해하기를 이어서 읽어요.

서버 인증이 안정되면 이후 commerce 문서는 대부분 같은 토큰 기반으로 연결돼요.