L’API, pour automatiser votre compte

Ce que vous y gagnez : lire et modifier des éléments de votre compte depuis vos propres programmes : télécharger vos factures dans votre comptabilité, ouvrir des tickets depuis votre système d’incidents, consulter le statut de vos services.

Deux façons de se connecter, qui ne servent pas à la même chose

Avec quoi	Pour quelle partie	Durée de validité
Clé d’API	Vos sites : sites web, domaines, DNS, e-mail, bases de données, FTP et certificats.	Elle n’expire pas tant que vous ne la révoquez pas.
Utilisateur et mot de passe (jeton JWT)	Factures, tickets, alertes et votre profil.	60 minutes, et il faut le renouveler.

Si ce que vous voulez, c’est automatiser vos sites — une sauvegarde nocturne, une étape de votre pipeline, un script qui crée le site de chaque nouveau client —, ce qu’il vous faut, c’est la clé d’API. C’est ce qui commence ci-dessous.

Important

Pour la partie sites, le jeton JWT ne fonctionne pas. Ce n’est pas qu’il soit déconseillé : il renvoie une erreur de permissions. Utilisez la clé.

Créer votre clé

Dans le panneau, dans Compte ‣ Clés pour l’IA. La clé n’est affichée qu’une seule fois : copiez-la à ce moment-là et rangez-la là où vous rangez vos mots de passe. Si vous la perdez, elle ne se récupère pas — on la révoque et on en crée une autre.

nxp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Ce que votre clé peut faire

Une clé tout juste créée ne fait que lire. Les permissions sont séparées parce que les risques ne sont pas les mêmes :

Permission	Ce qu’elle ouvre	Comment l’obtenir
`sitios:leer`	Consulter (`GET`)	À la création de la clé
`sitios:escribir`	Créer et modifier (`POST`, `PUT`, `PATCH`)	Demandez-le dans un ticket
`sitios:borrar`	Supprimer (`DELETE`)	Demandez-le dans un ticket

Supprimer n’est pas inclus dans écrire, et c’est voulu : créer un site en trop se corrige en le supprimant ; supprimer celui qu’il ne fallait pas, non.

S’il manque la permission à votre clé, la réponse vous dit laquelle manque. Vous n’avez pas à le deviner en tâtonnant.

L’utiliser

Un en-tête, dans chaque requête :

Authorization: Bearer nxp_tu_clave

Ou X-API-Key: nxp_tu_clave si votre outil ne vous laisse pas toucher à Authorization.

Un exemple complet, lister vos sites :

curl -H "Authorization: Bearer $HOSTBRID_TOKEN" \
     https://my.hostbrid.com/api/sites/v1/sites/

Et en créer un :

curl -X POST \
     -H "Authorization: Bearer $HOSTBRID_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"domain": "ejemplo.com", "php_version": "8.3"}' \
     https://my.hostbrid.com/api/sites/v1/sites/

Tip

Si vous préférez ne pas écrire de curl, il existe un outil en ligne de commande qui fait la même chose en une seule ligne.

La liste complète des opérations

Elle est sur https://my.hostbrid.com/api/docs/, et se consulte sans compte. Chaque opération indique la permission dont elle a besoin.

Vous ne voyez que ce qui est à vous

Tout est limité à votre compte. Demander par identifiant quelque chose qui appartient à un autre client renvoie 404, pas 403 : un 403 confirmerait que cet identifiant existe.

Limites

Chaque clé a sa propre limite de requêtes par minute. Si vous la dépassez, la réponse est un 429 : attendez et réessayez. Le compteur de l’API est indépendant de celui de la boutique, donc automatiser des sauvegardes ne vous prive pas du moteur de recherche de domaines sur le site.

Si vous pensez que la clé a fuité

Révoquez-la dans le panneau, sur le même écran où vous l’avez créée. Elle cesse d’être valable à l’instant. Créez-en ensuite une autre : il n’y a pas moyen de « changer le mot de passe » d’une clé, et c’est voulu.

Factures, tickets et profil : ça reste avec utilisateur et mot de passe

Cette partie n’accepte pas encore la clé. On demande un jeton :

POST /api/v1/auth/token/

{ "username": "tu-usuario", "password": "tu-contraseña" }

et elle répond access (60 minutes, celui qui s’utilise dans chaque requête) et refresh (7 jours, celui qui sert à en demander un autre, sur /api/v1/auth/token/refresh/).

Si vous avez la vérification en deux étapes activée, il faut envoyer en plus le code à six chiffres dans le champ otp, et uniquement au moment de demander le jeton, pas à chaque requête.

Important

Le jeton de renouvellement change à chaque fois que vous l’utilisez : la réponse en apporte un nouveau et le précédent cesse d’être valable. Gardez toujours le dernier.

C’est pourquoi cette partie ne convient pas aux processus sans surveillance : le renouvellement exige votre mot de passe et, avec la vérification en deux étapes, un code qu’un programme ne peut pas taper. Nous travaillons à ce que la clé serve ici aussi. Si c’est ce dont vous avez besoin, dites-le-nous dans un ticket : ça aide à le prioriser.

Ce qu’il y a dans la partie utilisateur et mot de passe

Filtré sur votre compte, comme tout le reste : vous ne voyez que ce qui est à vous.

Pour quoi faire	Où
Résumé de votre compte — les compteurs de tous les modules d’un coup	`GET /api/v1/dashboard/stats/`
Factures — les lister et les lire, avec numéro, HT, taxes, total et lignes de détail	`GET /billing/api/invoices/`
Abonnements — quelles offres vous avez et jusqu’à quand	`GET /billing/api/subscriptions/`
Paiements — l’historique	`GET /billing/api/payments/`
Données de facturation — vos données fiscales	`/billing/api/profiles/`
Consommation — les relevés d’utilisation qui sont facturés	`GET /billing/api/usage/`
Tickets — les ouvrir, les lire et répondre	`/tickets/api/tickets/`
Alertes — les notifications du panneau	`/notifications/api/v1/notifications/`
Vos clés SSH	`/accounts/api/ssh-keys/`
Votre profil	`/accounts/api/`

Les factures sont en lecture seule à dessein : c’est le système qui les émet, et une facture émise ne se supprime ni ne s’invente depuis l’extérieur.

Exemple avec le jeton : télécharger vos factures

En trois étapes :

1. POST /api/v1/auth/token/
   { "username": "…", "password": "…" }
   → guarda "access" y "refresh"

2. GET /billing/api/invoices/
   Authorization: Bearer <access>
   → la primera página de facturas

3. GET /billing/api/invoices/?page=2
   Authorization: Bearer <access>
   → las siguientes

Les listes sont paginées par 20. La réponse contient le lien vers la page suivante ; suivez ce lien jusqu’à ce qu’il n’y en ait plus.

Ce que vous pouvez faire dépend de votre rôle

Au sein d’une organisation il y a trois rôles, et l’API les respecte tout comme le panneau :

Administrateur et membre — peuvent lire et modifier.
Lecture seule — peuvent lire, et toute tentative de créer ou de supprimer répond que vous n’avez pas les permissions suffisantes.

Si une requête d’écriture vous renvoie une erreur de permissions et que vous pensez que ça ne devrait pas, regardez d’abord quel rôle vous avez dans l’organisation.

Ce qui n’est pas encore prêt

Quoi	Statut
La clé pour les factures, les tickets et le profil	Aujourd’hui la clé n’ouvre que la partie sites. L’autre reste avec utilisateur et mot de passe. En cours.
Déploiement depuis git (Projects) et son CLI	En développement. L’outil en ligne de commande qui existe déjà (Le terminal : hostbrid) est pour l’hébergement, pas pour ça.
Alertes automatiques vers vos systèmes (webhooks)	Pas encore disponibles pour les clients.

Problèmes fréquents

Avec la clé, tout me répond que je ne suis pas authentifié: Vérifiez que l’en-tête dit Bearer, une espace, puis la clé entière commençant par nxp_. Si ça continue, regardez dans le panneau que vous ne l’avez pas révoquée.
Avec la clé, les sites me donnent une erreur de permissions, et le reste aussi: Vous utilisez la clé contre les factures ou les tickets : là, elle ne vaut pas encore. Cette partie fonctionne avec utilisateur et mot de passe.
Avec le jeton, tout me répond que je ne suis pas authentifié: C’est presque toujours que les 60 minutes sont passées. Renouvelez le jeton. Et si vous l’utilisez contre /api/sites/v1/, là ça ne fonctionne pas : utilisez la clé.
Le rafraîchissement me dit que le jeton n’est pas valable: Vous en réutilisez un déjà consommé. Chaque renouvellement en renvoie un nouveau : gardez toujours le dernier. Si vous l’avez perdu, redemandez la paire avec utilisateur et mot de passe.
Je demande le jeton et il me le refuse alors que le mot de passe est bon: Vous avez la vérification en deux étapes activée et il manque le champ otp.
Il me répond que je n’ai pas les permissions: Soit votre rôle est en lecture seule, soit vous demandez quelque chose d’une autre organisation.

S’il vous manque quelque chose, dites-le

Cette partie est en train de grandir. Si vous avez besoin d’une donnée ou d’une opération qui n’est pas dans le tableau, ouvrez-nous un ticket en racontant ce que vous voulez automatiser. C’est la meilleure façon pour qu’elle apparaisse ici.