Reseller API：HMAC 署名でホスティングを自動発注

Reseller API でできること

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

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

ベース URL

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

API で実現できる操作

製品と価格の取得（KVM ルートサーバー、専用サーバー、ウェブスペース、Minecraft、VPN、無制限トラフィック）。
発注（Idempotency-Key により、ネットワーク再試行時の二重請求を防止します）。
自社サービスの一覧取得、ステータス確認、アクション実行（起動、停止、再起動、再インストール、停止、解約）。
自社サービスに限定した認証情報の取得（専用スコープ、監査ログ、アクセスごとに任意の確認メール）。
請求書の取得、クレジット残高の確認、請求書 PDF のダウンロード。
キーごとに Webhook を登録し、注文、サービス、請求書のイベントを受信できます（Stripe 互換の署名方式）。

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

本 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/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）を示します。注文は 24 時間「支払い待ち」状態となり、その後自動的にキャンセルされます。

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

はい。ただしご自身のサービスに限り、かつキー作成時に明示的に有効化した read:credentials スコープが必要です。アクセスごとに credentials.read という監査ログエントリーが生成され、必要に応じてアカウント登録メールアドレスに確認メールを送信できますので、密かな不正利用は不可能です。