Première requête à l’API Hostbrid : clé, permissions et cURL

L’API REST permet de connecter un script ou une application aux services de votre compte Hostbrid. Avant d’automatiser des changements, effectuez une requête en lecture, vérifiez que les ressources attendues apparaissent et identifiez la permission requise par chaque opération. La référence publique est générée depuis les routes actives du panneau : utilisez-la comme source de vérité lorsque les endpoints évoluent.

1. Créez et stockez une clé

Ouvrez Paramètres → clés API et créez une clé. Sa valeur complète ne s’affiche qu’une seule fois. Stockez-la dans un gestionnaire de secrets ou le mécanisme sécurisé de votre environnement ; ne la publiez pas dans Git, ne l’intégrez pas au JavaScript du navigateur et ne la collez pas dans un prompt ou une capture d’écran. Si quelqu’un la voit, révoquez-la et créez-en une autre.

Une nouvelle clé permet la lecture. Les permissions d’écriture, d’action sur les machines et de suppression sont séparées ; certaines doivent être demandées au support. N’accordez que la permission nécessaire à votre tâche. La clé reste active jusqu’à sa révocation ; elle n’expire pas au bout de peu de temps.

2. Effectuez une requête en lecture

Définissez HOSTBRID_API_KEY dans l’environnement protégé de votre terminal et consultez vos sites avec une requête GET :

curl --fail-with-body \
  -H "Authorization: Bearer $HOSTBRID_API_KEY" \
  https://my.hostbrid.com/api/sites/v1/sites/

La clé commence par nxp_. Si votre outil ne permet pas de configurer Authorization, vous pouvez envoyer la même clé dans X-API-Key. N’utilisez pas le jeton de session du panneau ni un JWT : l’API client utilise une clé longue.

Cet exemple ne fait que lire. Avant de créer ou modifier une ressource, vérifiez la méthode, le corps attendu et la permission dans la référence OpenAPI. La console affiche le schéma mais ne lance pas les requêtes depuis le navigateur. Chaque clé a sa propre limite de débit ; évitez les boucles de polling sans changement.

3. Lisez le résultat avant de continuer

Traitez la réponse comme des données de votre compte. Vérifiez le statut HTTP et le JSON avant de déclarer une tâche terminée. Un 200 ne prouve pas à lui seul que le changement souhaité a été enregistré ; une réponse de lecture confirme uniquement cette consultation.

Réponse	Vérification
`401`	La clé manque, a été mal copiée, révoquée ou l’en-tête est incorrect.
`403`	La clé n’a pas la permission requise. Vérifiez l’autorisation indiquée dans la référence ; ne devinez pas les méthodes.
`404`	La route ou la ressource n’est pas disponible dans votre compte. Les ressources d’un autre compte ne sont pas révélées.
`429`	La limite par clé est dépassée. Réduisez la fréquence et évitez les répétitions inutiles.

Ne relancez pas aveuglément un POST qui pourrait créer une commande ou une ressource : vérifiez d’abord le résultat de la requête précédente. N’enregistrez pas les en-têtes d’authentification dans les logs et ne partagez pas de capture qui les affiche.

Après votre première requête

Pour consulter le catalogue complet, les permissions par opération et les schémas de requête, ouvrez la référence API REST. Pour les tâches en ligne de commande, lisez le guide CLI. Pour connecter un assistant compatible MCP, consultez API, CLI et MCP pour automatiser Hostbrid et le guide de connexion d’une IA.

Si vous automatisez l’achat et le cycle de vie du matériel, consultez le guide de l’API des serveurs dédiés.

Ce guide n’accorde aucune permission, n’achète pas de service et ne prouve pas qu’un script quelconque est sûr. Commencez par des lectures et n’ajoutez des permissions d’écriture que pour une action précise.