クイックスタート

1. API キーを作成する

カスタマーポータルの「KernelHost API」にログインし、キーを作成します。実際に必要なスコープだけを選択してください（デフォルト：読み取り専用）。シークレットは一度しか表示されないため、お使いのシークレットマネージャーに安全に保管してください。

2. 認証情報を保管する

キーとシークレットを環境変数として保存してください。コード内、リポジトリ内には絶対に保存しないでください。

# .env またはシェルプロファイル
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. 最初のリクエストを送信する

利用可能な製品の一覧を取得します。署名はメソッド、パス、タイムスタンプ、ノンス、ボディハッシュから生成されます。

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

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

4. 発注する

重要：POST /v1/orders には Idempotency-Key とホスト名が必要です。ネットワークエラーの後に同じキーで再試行すると、注文が二重に作成されることはなく、同じレスポンスが返されます。省略した設定オプション（拠点やオペレーティングシステムなど）には、ショップで最初に表示されている値が適用されます。

BODY='{"product_id":42,"billing_cycle":"monthly","hostname":"web01.example.com"}'
IDEM="order-web01-$(date +%Y%m%d)"
BODY_SHA256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
SIG_INPUT=$(printf 'POST\n/v1/orders\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')

curl -X POST https://www.kernelhost.com/cp/kernelhost_api/v1/orders \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  --data "$BODY"

5. ステータスを確認し、認証情報を取得する

注文のレスポンスには service_ids が含まれます。status が active になり、IP アドレスが設定されるまで GET /v1/services/{id} を繰り返し照会してください。セットアップには通常、数秒から数分かかります。その後、GET /v1/services/{id}/credentials（スコープ read:credentials）でホスト名、IP アドレス、ユーザー名、パスワードを取得できます。取得した情報は、たとえば Ansible のインベントリーに利用できます。

kh_get() {
  TS=$(date +%s)
  NONCE=$(openssl rand -hex 16)
  BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
  SIG_INPUT=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$TS" "$NONCE" "$BODY_SHA256")
  SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')
  curl -s "https://www.kernelhost.com/cp/kernelhost_api$1" \
    -H "KH-Key: $KH_KEY" \
    -H "KH-Timestamp: $TS" \
    -H "KH-Nonce: $NONCE" \
    -H "KH-Signature: $SIG"
}

kh_get /v1/services/1234
kh_get /v1/services/1234/credentials

6. Webhook URL を登録する（任意）

HTTPS URL はキーごとにすでに登録できます。イベントの配信は現在準備中のため、それまでは手順 5 のステータス照会をご利用ください。