Reseller API: HMAC 서명 요청으로 호스팅 자동 주문

Reseller API가 제공하는 기능

KernelHost Reseller API는 평소 고객 포털에서 클릭으로 수행하시던 주문 및 관리 작업을 그대로 제공해요. 리셀링 비즈니스를 자동화하고, KernelHost 제품을 자체 프론트엔드나 청구 시스템에 통합하며, 키마다 권한 범위, 속도 제한, IP 허용 목록을 완전히 제어하실 수 있어요.

모든 호출은 HMAC-SHA256으로 서명되고 재전송 공격(Replay)으로부터 보호되며, 멱등 방식으로 처리되고(주문 시 필수) 변조 방지 감사 로그에 기록되며, 원하시면 웹훅으로 추가 확인이 이뤄져요. 결제는 먼저 크레딧 잔액에서, 그다음 등록된 카드에서 차감돼요. 새 카드는 보안상 고객 포털에서만 추가하실 수 있어요(3-D Secure 2 적용).

베이스 URL

https://www.kernelhost.com/cp/kh_reseller_api/v1

API로 할 수 있는 일

제품 및 가격 조회 (KVM 루트서버, 전용서버, 웹스페이스, Minecraft, VPN, 무제한 트래픽).
주문 처리 (네트워크 재시도 시 Idempotency-Key가 중복 결제를 방지해요).
본인 서비스 목록 조회, 상태 확인, 액션 실행 (시작, 정지, 재부팅, 재설치, 일시 정지, 해지).
본인 서비스의 자격증명만 조회 (별도 권한 범위, 감사 로그 기록, 접근 시 선택적 확인 메일).
청구서 조회, 크레딧 잔액 확인, 청구서 PDF 다운로드.
키 단위 웹훅 등록, 주문/서비스/청구서 이벤트 수신 (Stripe 호환 서명 방식).

최고 수준의 보안 설계

모든 호출이 직접적인 재무 영향을 발생시킬 수 있고 민감한 서버 자격증명에 접근할 수 있다는 전제로 설계됐어요. 따라서 보안 기준은 일반적인 REST 기본값보다 훨씬 높아요.

메서드, 경로, 타임스탬프, 논스, 본문 해시에 대한 HMAC-SHA256 요청 서명. 상수 시간 비교 적용.
재전송 방어: 타임스탬프 허용 범위 +-300초, 일회용 논스 캐시 600초 유지.
시크릿은 AES-256-GCM 암호문으로만 저장돼요. 평문은 서명 검증을 위해 메모리에서 잠시만 존재해요. 마스터 키는 데이터베이스 외부에 보관돼요.
키마다 세분화된 권한 범위. 위험한 권한 범위(read:credentials, write:orders)는 명시적으로 활성화해야 하고, 기본값은 읽기 전용이에요.
데이터베이스 수준의 데이터 격리: 모든 쿼리가 계정 ID로 강제 필터링되어 다른 테넌트 접근이 구조적으로 불가능해요.

예시: 본인 계정 정보 조회

요청 전체가 시크릿으로 서명돼요. 시크릿은 클라이언트 메모리를 벗어나지 않으며, 전송되는 것은 서명뿐이에요.

TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $2}')
SIG_INPUT=$(printf 'GET\n/v1/me\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $2}')

curl https://www.kernelhost.com/cp/kh_reseller_api/v1/me \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG"

자주 묻는 질문

Reseller API는 누가 사용할 수 있나요?

기존 KernelHost 고객이라면 누구나 "내 계정 → Reseller API"에서 라벨, 권한 범위, IP 허용 목록을 직접 지정해 키를 발급하실 수 있어요. 별도의 리셀러 계약은 필요 없으며, 공개 판매 중인 모든 제품을 API로 주문하실 수 있어요.

주문 시 결제는 어떻게 이뤄지나요?

순서: 먼저 크레딧 잔액, 그다음 등록된 결제 수단(3-D Secure 2 적용 신용카드)이에요. 결제가 거절되거나 카드가 등록돼 있지 않으면 API는 HTTP 402 "Payment Required"와 함께 구체적인 사유(insufficient_credit_and_no_card, card_declined, card_expired)를 반환해요. 주문은 "pending payment" 상태로 24시간 유지된 뒤 자동으로 취소돼요.

API로 서비스 비밀번호를 조회할 수 있나요?

네, 본인 서비스에 한해 가능해요. 키 발급 시 명시적으로 활성화한 read:credentials 권한 범위가 있어야 하며, 호출마다 credentials.read 감사 로그가 기록돼요. 원하시면 등록된 계정 주소로 확인 메일을 추가로 받으실 수 있어 은밀한 오남용은 불가능해요.