KernelHost API (Reseller API, 리셀러 API): HMAC 서명 요청으로 호스팅 자동 주문

KernelHost API (Reseller API)가 제공하는 기능

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

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

베이스 URL

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

API로 할 수 있는 일

제품 및 가격 조회 (KVM 루트서버, 전용서버, 웹스페이스, Minecraft, VPN, 무제한 트래픽).
주문 처리 (네트워크 재시도 시 Idempotency-Key가 중복 결제를 방지해요).
본인 서비스 목록 조회, 상태 확인 및 액션 실행: 시작, 정지, 재부팅, 결제 기간 종료 시점의 해지와 해지 철회.
본인 서비스의 자격증명만 조회 (별도 권한 범위, 감사 로그 기록, 접근 시 선택적 확인 메일).
청구서 조회, 크레딧 잔액 확인, 청구서 PDF 다운로드.
키마다 웹훅 URL 등록. 이벤트 전송(주문, 서비스, 청구서 이벤트)은 현재 준비 중이며, 그때까지는 GET /v1/orders/{id}와 GET /v1/services/{id}로 상태를 조회하십시오.

최고 수준의 보안 설계

모든 호출이 직접적인 재무 영향을 발생시킬 수 있고 민감한 서버 자격증명에 접근할 수 있다는 전제로 설계됐어요. 따라서 보안 기준은 일반적인 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/kernelhost_api/v1/me \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG"

자주 묻는 질문

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

기존 KernelHost 고객이라면 누구나 고객 포털의 "KernelHost API" 메뉴에서 키를 생성하실 수 있으며, 키마다 라벨, 권한 범위, IP 허용 목록을 따로 지정하실 수 있습니다. 키 생성, 교체, 폐기는 계정 소유자만 할 수 있습니다. 별도의 리셀러 계약은 필요하지 않으며, 공개 판매 중인 모든 제품을 API로 주문하실 수 있습니다.

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

결제는 먼저 크레딧 잔액으로, 그다음 등록된 결제 수단으로 이루어집니다. 결제가 실패하거나 등록된 카드가 없으면 API는 HTTP 402 "Payment Required"와 함께 구체적인 사유(insufficient_credit_and_no_card, card_declined, credit_apply_failed)를 반환하고 주문을 즉시 취소하므로, 미결제 주문이 남지 않습니다.

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

네, 본인 서비스에 한해서만, 그리고 read:credentials 권한 범위가 명시적으로 부여된 경우에만 가능합니다. 이 권한 범위는 키 생성 시 별도로 활성화해야 합니다. 응답에는 호스트 이름, IP 주소, 사용자 이름, 비밀번호가 포함됩니다. 접근할 때마다 감사 로그에 credentials.read 항목이 기록되고 계정 이메일 주소로 확인 메일이 발송되므로, 은밀한 오남용도 반드시 드러납니다.