KernelHost API

Ce que fait la KernelHost API (API Revendeur)

L'API Revendeur KernelHost expose exactement les actions de commande et de gestion que vous effectueriez sinon en cliquant dans le portail client. Elle vous permet d'automatiser votre activité de revente, d'intégrer les produits KernelHost dans votre propre interface ou système de facturation, et de garder le contrôle total sur les permissions, les limitations de débit et la liste blanche d'adresses IP de chaque clé.

Chaque appel est signé en HMAC-SHA256, protégé contre le rejeu, traité de manière idempotente (obligatoire pour les commandes) et consigné dans un journal d'audit infalsifiable. Les paiements sont débités d'abord de votre solde de crédit, puis de votre carte enregistrée. Pour des raisons de sécurité, les nouvelles cartes ne peuvent être ajoutées que dans le portail client (3-D Secure 2).

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

Table des matières

• Démarrage rapide en 5 minutes
• Authentification (HMAC-SHA256)
• Référence des points de terminaison
• Codes d'erreur (RFC 7807)
• SDK et exemples de code
• Sécurité et bonnes pratiques
• Journal des modifications

Ce que vous pouvez faire

• Parcourir les produits et les prix (serveurs racines KVM, serveurs dédiés, hébergement web, Minecraft, VPN, trafic illimité).
• Passer des commandes (l'en-tête Idempotency-Key protège contre les doubles débits lors des nouvelles tentatives réseau).
• Lister vos propres services, vérifier leur statut et exécuter des actions : start, stop, reboot, ainsi que la résiliation en fin de période de facturation et son annulation.
• Lire les identifiants de vos propres services uniquement (permission distincte, traçabilité par audit, e-mail de confirmation optionnel à chaque accès).
• Récupérer vos factures, vérifier votre solde de crédit, télécharger les PDF de factures.
• Enregistrer une URL de webhook par clé. L'envoi des événements de commande, de service et de facture est en préparation ; d'ici là, consultez le statut via GET /v1/orders/{id} et GET /v1/services/{id}.

Conception à sécurité maximale

L'API est conçue en partant du principe que chaque appel a un impact financier direct et peut exposer des identifiants de serveur sensibles. La base de sécurité dépasse donc largement les normes REST habituelles.

• Signature de requête HMAC-SHA256 sur méthode, chemin, horodatage, nonce et empreinte du corps. Comparaison à temps constant.
• Protection anti-rejeu : fenêtre d'horodatage de +-300s, cache de nonce à usage unique pendant 600s.
• Les secrets sont uniquement persistés sous forme de cryptogrammes AES-256-GCM. Le clair n'existe que de manière transitoire en mémoire pour vérifier la signature. La clé maîtresse réside hors de la base de données.
• Permissions granulaires par clé. Les permissions dangereuses (read:credentials, write:orders) doivent être activées explicitement. Le paramétrage par défaut est en lecture seule.
• Isolation des données au niveau base de données : chaque requête filtre strictement sur votre identifiant de compte. L'accès entre locataires est impossible par conception.

Exemple : interroger les informations de votre compte

La requête est intégralement signée avec votre secret. Le secret ne quitte jamais la mémoire du client ; seule la signature est transmise.

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"

Questions fréquentes

Qui peut utiliser l'API Revendeur ?

Tout client KernelHost existant peut créer des clés dans le portail client via l'entrée de menu "KernelHost API", chacune avec son propre libellé, ses permissions et sa liste blanche d'adresses IP. Seul le titulaire du compte peut créer, renouveler ou révoquer des clés. Aucun accord de revente distinct n'est requis : tous les produits listés publiquement peuvent être commandés via l'API.

Comment les commandes sont-elles payées ?

Le paiement s'effectue d'abord avec votre solde de crédit, puis avec votre moyen de paiement enregistré. En cas d'échec du paiement ou si aucune carte n'est enregistrée, l'API renvoie HTTP 402 "Payment Required" avec un motif précis (insufficient_credit_and_no_card, card_declined, credit_apply_failed) et annule aussitôt la commande, si bien qu'aucune commande impayée ne subsiste.

Puis-je lire les mots de passe des services via l'API ?

Oui, mais uniquement pour vos propres services et uniquement avec la permission explicite read:credentials, qui doit être activée séparément lors de la création de la clé. La réponse contient le nom d'hôte, les adresses IP, le nom d'utilisateur et le mot de passe. Chaque accès génère une entrée d'audit credentials.read ainsi qu'un e-mail de confirmation à l'adresse du compte : aucun abus commis à votre insu ne passe donc inaperçu.

Que se passe-t-il si mon secret est compromis ?

Vous renouvelez le secret d'un seul clic dans l'espace client et l'ancien secret devient immédiatement invalide. Les tentatives d'authentification échouées sont journalisées et limitées par IP source, mais ne verrouillent jamais votre clé : personne ne peut bloquer votre intégration simplement en connaissant l'ID public de votre clé.