Démarrage rapide

1. Créer une clé API

Connectez-vous au portail client sous "KernelHost API" et créez une clé. Ne sélectionnez que les permissions dont vous avez réellement besoin (par défaut : lecture seule). Le secret n'est affiché qu'une seule fois : conservez-le en lieu sûr dans votre gestionnaire de secrets.

2. Stocker les identifiants

Enregistrez la clé et le secret comme variables d'environnement. Jamais dans le code, jamais dans un dépôt.

# .env ou profil shell
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. Envoyer votre première requête

Listez les produits disponibles. La signature est construite sur méthode, chemin, horodatage, nonce et empreinte du corps.

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. Passer une commande

Important : POST /v1/orders exige un nom d'hôte ainsi qu'un en-tête Idempotency-Key. Si vous renvoyez la requête avec la même Idempotency-Key après une erreur réseau, vous recevez la même réponse, sans qu'une deuxième commande soit créée. Les options de configuration que vous n'indiquez pas (par exemple l'emplacement ou le système d'exploitation) prennent la première valeur proposée dans la boutique.

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. Vérifier le statut et récupérer les identifiants

La réponse à la commande indique les service_ids. Interrogez GET /v1/services/{id} jusqu'à ce que le champ status passe à active et qu'une adresse IP soit attribuée ; le provisionnement prend généralement de quelques secondes à quelques minutes. Ensuite, GET /v1/services/{id}/credentials (permission read:credentials) renvoie le nom d'hôte, les adresses IP, le nom d'utilisateur et le mot de passe, par exemple pour votre inventaire 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. Enregistrer une URL de webhook (optionnel)

Vous pouvez dès à présent enregistrer une URL HTTPS par clé. L'envoi des événements est en préparation ; d'ici là, interrogez le statut comme décrit à l'étape 5.