Ouvrir l'API à un partenaire
Introduction
Section titled “Introduction”Une clé d’API permet à un partenaire, ou à l’un de vos propres outils, d’interroger Gward depuis ses serveurs, sans compte utilisateur ni session. C’est l’accès adapté aux échanges entre systèmes : alimenter un outil de pilotage, croiser vos données de supervision avec celles d’un prestataire, automatiser un export.
Une clé est en lecture seule et limitée dans le temps : elle expire au plus tard 90 jours après sa création.
Prérequis
Section titled “Prérequis”- Rôle Administrateur ou supérieur sur le compte Gward
- Un MFA récent si le MFA est activé pour votre compte (voir Sécurité de la plateforme)
Créer une clé
Section titled “Créer une clé”- Ouvrez Paramètres → Clés d’API.
- Cliquez sur Nouvelle clé.
- Nommez-la d’après le partenaire qui l’utilisera.
- Choisissez sa validité : 30, 60 ou 90 jours. Il n’existe pas de clé sans expiration.
- Validez : la clé complète s’affiche, accompagnée d’un exemple d’appel qui permet au partenaire de vérifier qu’elle fonctionne.
Utiliser la clé
Section titled “Utiliser la clé”Le partenaire joint la clé à chacune de ses requêtes, dans un en-tête HTTP dédié. Le format d’appel et la liste des données accessibles lui sont communiqués lors de la mise en place de l’échange.
Une clé est un secret de serveur : elle ne doit jamais être placée dans une page web, une application mobile ou un dépôt de code, où n’importe qui pourrait la lire.
Ce qu’une clé permet
Section titled “Ce qu’une clé permet”| Clé d’API | |
|---|---|
| Lecture des données ouvertes aux partenaires | Oui |
| Accès à l’interface web | Non |
| Modification de la configuration | Non |
| Prise en main d’un agent (LiveControl) | Non |
| Lecture des dashboards affichés sur les écrans muraux | Non, ces écrans ont leur propre lien |
Le nombre de requêtes par minute est limité pour chaque clé. Au-delà, la plateforme répond au partenaire en lui indiquant combien de temps patienter avant de réessayer.
Expiration et renouvellement
Section titled “Expiration et renouvellement”La liste des clés affiche le nombre de jours restants. À l’approche de l’échéance, il passe en orange ; une fois la clé expirée, en rouge.
Pour éviter toute interruption, cliquez sur Renouveler avant l’échéance :
- Une nouvelle clé du même nom est créée, avec un nouveau secret et sa propre validité.
- L’ancienne clé reste valable jusqu’à sa propre expiration : le partenaire a le temps d’installer la nouvelle, sans coupure.
- Une fois la bascule faite, révoquez l’ancienne clé.
Révoquer une clé
Section titled “Révoquer une clé”Dans Paramètres → Clés d’API, cliquez sur Révoquer sur la ligne de la clé. Les appels avec cette clé sont refusés immédiatement. La révocation est définitive, mais la clé reste visible dans la liste pour garder la trace de son utilisation.
Révoquez sans attendre en cas de doute : fin de collaboration avec un partenaire, départ d’un prestataire, clé exposée par erreur.
Suivi et traçabilité
Section titled “Suivi et traçabilité”La liste des clés indique, pour chacune :
- sa partie publique, qui permet de la reconnaître sans révéler le secret ;
- la date de création et son auteur ;
- le dernier appel et l’adresse d’où il provient ;
- son statut : active, expirée ou révoquée.
Chaque création, renouvellement et révocation est enregistré dans le journal de sécurité, avec son auteur.
Bonnes pratiques
Section titled “Bonnes pratiques”- Une clé par partenaire : vous pourrez couper un accès sans toucher aux autres.
- La validité la plus courte compatible avec votre organisation.
- Renouveler avant l’échéance, puis révoquer l’ancienne clé dès que le partenaire a basculé.
- Surveiller le dernier appel : une clé qui ne sert plus doit être révoquée ; une adresse d’appel inattendue doit alerter.