Introduction à l’utilisation de l’API Cyberwatch

Les utilisateurs de Cyberwatch ont accès à une API permettant d’interagir avec la majeure partie des ressources visibles dans l’application. Cet accès peut permettre, par exemple, l’automatisation de certaines tâches, ou l’obtention de résultats personnalisés…

Cette page constitue une introduction au fonctionnement et à l’utilisation de cette API.

Interagir avec l’API Cyberwatch

L’API Cyberwatch retournant des réponses format JSON, il est possible d’utiliser nativement un client curl, la cmdlet PowerShell Invoke-WebRequest, ou notre client Python afin de l’interroger.

S’authentifier auprès de l’API et tester sa connexion

L’utilisation de l’API, quelle que soit la route interrogée, nécessite d’être authentifié par les clés d’API d’un utilisateur Cyberwatch ayant un rôle Administrateur.

Ces clés d’API peuvent être générées depuis la GUI Cyberwatch, dans l’onglet Mon Profil > Clés d’API, de chaque Administrateur Cyberwatch.

Ces identifiants peuvent-être utilisés via les deux modes d’authentification proposés : le basic-auth et l’apiAuth. Nous documentons l’usage de curl, de la cmdlet PowerShell Invoke-WebRequest, ou notre client d’API Python. Le mode d’authentification privilégié dans les exemples de notre documentation est le basic-auth. Plus d’informations concernant l’apiAuth sont disponibles ici.

Tester sa connexion

Les commandes référencées ci-dessous vous permettent de tester la validité de l’identifiant utilisé et effectuent un test de communication avec votre API Cyberwatch. En cas de succès, un id utilisateur vous est retourné.

Cette interrogation ne nécessite qu’un identifiant d’API disposant des droits de lecture seule. Il peut donc par la suite être nécessaire de vérifier le niveau d’accès dont dispose l’identifiant utilisé en fonction des requêtes qui seront effectuées.

Vous trouverez ci-joint des exemples détaillés de l’exécution de ce test de connexion via curl, la cmdlet PowerShell Invoke-WebRequest, ou notre client d’API Python.

Diagnostiquer les problèmes de connexions

Vous rencontrez une erreur 401

Une erreur 401 signifie que l'authentification a échoué. Pour y remédier, il faudra, tout d'abord, vérifier que les clés renseignées sont correctes. Dans un second temps, vous devriez également vérifier que l'URL correspond à celle de l'instance Cyberwatch souhaitée.

Vous rencontrez une erreur 403

Lorsque cette erreur survient, un problème de privilège est en cause. Il est possible que les clés d'API aient été générées avec un compte n'ayant pas les droits administrateur. Un autre cas possible est l'utilisation de clés ne possédant pas d'accès à l'API, par exemple celles pour l'installation d'agents. Afin de vérifier ces éléments, il faudra se rendre sur l'interface web de l'application Cyberwatch. Une fois connecté, allez sur la page "Mon profil". Le champ "Rôle" correspond au niveau de privilège de votre compte. Dans le but d'utiliser l'API, ce dernier doit être "Administrateur". Rendez-vous ensuite en bas de la page, puis sur "Voir mes clés d'API". Vous aurez alors le détail des clés d'API lié à votre compte, ainsi que leur niveau de droit. Dans un but uniquement de récupération de données depuis l'API, le mode "Lecture seule" suffira. Sinon, il faudra que la clé dispose du niveau d'accès "Complet".

Structures des routes et des retours de l’API

Les différents points d’accès de l’API sont consultables depuis une documentation Swagger accessible depuis votre application via le bouton </> situé en haut à droite de la page.

Depuis Swagger, chaque section décrit la route utilisée ainsi que la liste des paramètres disponibles et un exemple de la structure de données retournées par la requête. Il est d’ailleurs possible de générer la liste en question au format OpenAPI depuis ici, afin de l’importer dans d’autres outils comme Postman. Swagger vous permet aussi de générer directement des requêtes curl authentifiées et de les exécuter à la volée, pour tester les retours API de votre instance.

Comme pour toute requête faite à l’API, Swagger nécessite d’être authentifié via un identifiant d’API comme indiqué précédemment.

Nous vous recommandons de les configurer directement via le bouton Authorize de Swagger. Lorsque les identifiants sont ainsi fournis, Swagger génère directement le header d’authentification curl, ce qui rend la commande facilement réutilisable.

Clients d’API dépréciés

Depuis la version 13.0 de Cyberwatch, nos anciens clients d’API PowerShell et Python sont dépréciés.

Pour toute question sur le sujet, ou besoin d’accompagnement sur la migration d’un script d’API d’une ancienne version vers la nouvelle, vous pouvez nous contacter par e-mail à support@cyberwatch.fr, ou par téléphone au +33 1 84 80 88 84.