Créer une clé API et utiliser l'API de l'espace client OuiHeberg

L'espace client OuiHeberg a sa propre API. Avec une clé API, un script ou un logiciel interroge votre compte sans passer par l'interface, pour suivre vos domaines ou vos factures par exemple. Ce guide montre où créer une clé, comment lire la documentation, faire un premier appel, tenir compte des limites et révoquer une clé.

Ouvrir la rubrique Clés API

Connectez-vous à dash.ouiheberg.com.
En haut à droite, cliquez sur votre nom, puis sur Mon profil.
Dans le menu de la page Paramètres du compte, choisissez Clés API.

Le lien direct est dash.ouiheberg.com/settings?section=apikeys.

Rubrique Clés API des paramètres du compte, avec les boutons Documentation API et Nouvelle clé

La rubrique liste vos clés. Tant que vous n'en avez créé aucune, elle affiche Aucune clé API pour le moment. Chaque clé n'accède qu'à votre propre compte.

Créer une clé

Cliquez sur Nouvelle clé.
Donnez-lui un nom parlant, celui du script ou de l'outil qui va l'utiliser. Le jour où ce script disparaît, vous saurez quelle clé révoquer.
Validez la création de la clé.
dash affiche la clé une seule fois. Copiez-la tout de suite et rangez-la en lieu sûr, dans un gestionnaire de mots de passe par exemple. Elle ne pourra plus être relue.

Une clé peut aussi être limitée à certaines adresses IP, celles des serveurs qui l'utilisent. Sans liste, elle fonctionne depuis n'importe quelle adresse. Avec une liste, un appel venu d'une autre adresse est refusé.

💡 Si dash vous demande d'activer la double authentification avant de créer une clé, suivez notre guide Activer la double authentification (2FA), puis revenez dans Clés API.

Lire la documentation de l'API

Le bouton Documentation API de la rubrique ouvre dash.ouiheberg.com/settings/api-docs.

Page Documentation API avec l'introduction, l'authentification, les erreurs et la liste des endpoints par famille

Cette documentation est taillée pour votre compte. Elle ne montre que les endpoints qui vous sont ouverts, rangés par famille (domaines, boutique, compte…). Chaque ligne porte sa méthode, GET pour lire, POST, PUT ou PATCH pour envoyer ou modifier, DEL pour supprimer. En haut, des pastilles indiquent combien d'endpoints vous sont ouverts et combien modifient votre compte. Le champ de recherche, en haut à gauche, retrouve un endpoint à partir d'un mot comme « facture » ou « domaine ».

Retenez trois repères de l'introduction.

L'adresse de base de l'API est https://dash.ouiheberg.com/api/v1.
Toutes les réponses sont en JSON. Envoyez l'en-tête Accept: application/json, et ajoutez Content-Type: application/json quand la requête a un corps.
En haut de la page, Mes clés API vous ramène à vos clés et Espace client à l'espace client.

Un endpoint dont vous avez besoin n'apparaît pas ? Il n'est pas ouvert à votre compte. Écrivez-nous par ticket en précisant ce que vous souhaitez automatiser.

Faire un premier appel

Chaque appel porte votre clé dans l'en-tête Authorization, précédée du mot Bearer. Gardez la clé dans une variable d'environnement, ici OH_API_KEY, plutôt que de l'écrire en clair dans vos commandes. Une clé collée dans un script partagé ou dans un ticket est une clé à révoquer.

Voici le premier appel proposé par la documentation.

curl -H "Authorization: Bearer $OH_API_KEY" -H "Accept: application/json" https://dash.ouiheberg.com/api/v1/domains/check

Pour voir les paramètres d'un endpoint et ce qu'il renvoie, dépliez-le dans la documentation.

Essayer depuis la page

La documentation permet aussi de lancer un appel sans rien installer. Collez une de vos clés dans la page. Elle n'y est pas enregistrée et disparaît si vous rechargez. Lancez ensuite l'essai depuis l'endpoint déplié.

Ces essais sont de vrais appels. Un appel qui modifie votre compte le modifie pour de bon, et la page vous demande de confirmer avant l'envoi. Un appel qui passe une commande émet une vraie facture, exactement comme depuis la boutique.

Importer dans Postman

La rubrique Importer dans Postman propose une collection prête à importer, avec vos endpoints rangés par famille. Le fichier ne contient pas votre clé. Vous la renseignez dans Postman, dans la variable prévue pour cela.

Dans Postman, rien ne vous redemande de confirmer. Un appel qui modifie votre compte ou qui passe une commande part dès que vous l'envoyez.

Les limites d'appels

Chaque clé a sa propre limite d'appels par minute et par jour, fixée à sa création. Tous les appels comptent, y compris les essais lancés depuis la documentation. La rubrique Limites d'appels de la documentation détaille ce fonctionnement.

Au-delà, l'API répond par une erreur 429. Prévoyez une pause dans vos scripts plutôt que de relancer l'appel en boucle. La limite par minute se libère au bout d'une minute, celle du jour le lendemain.

Comprendre les erreurs

Un refus renvoie un code HTTP et un corps JSON. Le champ code donne la raison exacte et reste stable d'une version à l'autre. C'est lui que vos programmes doivent lire. Le champ message s'adresse à un humain.

Réponse	Signification
`401`	La clé est absente, inconnue, désactivée ou expirée. Vérifiez qu'elle a été copiée en entier.
`403` `ip_not_allowed`	La clé n'accepte que certaines adresses IP, et l'appel vient d'une autre.
`403` `endpoint_not_granted`	Cet endpoint n'est pas ouvert à votre compte. Écrivez-nous pour l'obtenir.
`403` `route_not_allowed`	L'endpoint est ouvert à votre compte, mais cette clé ne le couvre pas. Modifiez la clé ou utilisez-en une autre.
`403` `api_access_blocked`	L'accès API de votre compte est suspendu. Écrivez-nous pour en connaître la raison.
`429` `rate_limit_exceeded`	La limite par minute de la clé est atteinte. La réponse indique le délai d'attente.
`429` `daily_quota_exceeded`	La limite du jour de la clé est atteinte.

Révoquer une clé

Révoquez une clé dès qu'elle ne sert plus, ou au moindre doute, si elle a été collée dans un ticket, partagée dans un script ou laissée sur un ordinateur perdu.

Ouvrez Paramètres du compte › Clés API.
Sur la ligne de la clé, cliquez sur Révoquer.

Les programmes qui utilisaient cette clé reçoivent désormais une erreur 401. S'ils doivent continuer à tourner, créez une nouvelle clé et remplacez l'ancienne dans leur configuration.

💡 Vous êtes revendeur ? Les clés de l'API revendeur ne se créent pas ici, mais depuis l'espace revendeur, que l'on ouvre par la rubrique Compte revendeur.

Besoin d'aide ?

Pour faire ouvrir un endpoint ou rétablir un accès API, ouvrez un ticket depuis Tickets › Ouvrir un ticket (dash.ouiheberg.com/tickets/new) et décrivez ce que vous souhaitez automatiser. Ne collez jamais votre clé dans le ticket.
Vous pouvez aussi nous écrire sur notre Discord.