KernelHost API（Reseller API、リセラー API）：HMAC 署名でホスティングを自動発注

KernelHost API（Reseller API）でできること

KernelHost Reseller API は、カスタマーポータルでクリック操作する発注および管理アクションをそのまま API として公開しています。リセラー業務を自動化し、KernelHost 製品を独自のフロントエンドや課金システムに統合し、キーごとのスコープ、レート制限、IP 許可リストを完全に制御できます。

すべてのリクエストは HMAC-SHA256 で署名され、リプレイ攻撃から保護され、冪等に処理され（発注では必須）、改ざん検知付きの監査ログに記録されます。支払いはまずクレジット残高から、次に登録済みのカードから引き落とされます。新しいカードは、セキュリティ上の理由からカスタマーポータルでのみ登録できます（3-D Secure 2 認証）。

ベース URL

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

API で実現できる操作

製品と価格の取得（KVM ルートサーバー、専用サーバー、ウェブスペース、Minecraft、VPN、無制限トラフィック）。
発注（Idempotency-Key により、ネットワーク再試行時の二重請求を防止します）。
ご自身のサービスの一覧取得、ステータス確認、アクションの実行（起動、停止、再起動、請求期間終了時の解約、およびその取り消し）。
自社サービスに限定した認証情報の取得（専用スコープ、監査ログ、アクセスごとに任意の確認メール）。
請求書の取得、クレジット残高の確認、請求書 PDF のダウンロード。
キーごとに Webhook URL を登録できます。イベント（注文、サービス、請求書）の配信は現在準備中です。それまでは GET /v1/orders/{id} と GET /v1/services/{id} でステータスを照会してください。

最高水準のセキュリティ設計

本 API は、すべての呼び出しが直接的な金銭的影響を持ち、機微なサーバー認証情報にアクセスし得るという前提で設計されています。そのためセキュリティ基準は通常の 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 は具体的な理由（insufficient_credit_and_no_card、card_declined、credit_apply_failed）とともに HTTP 402 "Payment Required" を返し、注文を直ちにキャンセルします。そのため、未払いの注文が残ることはありません。

API でサービスのパスワードを取得できますか。

はい。ただし、ご自身のサービスに限り、明示的なスコープ read:credentials を付与したキーでのみ取得できます。このスコープはキーの作成時に個別に有効化する必要があります。レスポンスにはホスト名、IP アドレス、ユーザー名、パスワードが含まれます。アクセスのたびに監査ログエントリー credentials.read が作成され、アカウントに登録されたメールアドレスへ確認メールが送信されます。そのため、密かな不正利用も見逃されることはありません。