API REST : vue d'ensemble

Disponibilité

L’API REST et les webhooks sont disponibles sur le plan Business. Les plans inférieurs utilisent la console. La page API et extensions présente les intégrations prêtes à l’emploi.

Principes

L’API est une API REST au sens strict :

• tout le trafic passe par HTTPS sur le port 443 ;
• les réponses sont en JSON ;
• l’authentification se fait par jeton, émis depuis la console et révocable à tout moment ;
• chaque appel est consigné dans le journal d’audit chaîné de l’espace.

Les exemples ci-dessous sont indicatifs : les chemins et paramètres exacts figurent dans la documentation de référence de votre espace.

Authentification

Un jeton d’API s’obtient dans la console, section API. Traitez-le comme un secret : il agit au nom de l’espace dans les limites de son périmètre.

GET /v1/devices
Authorization: Bearer <VOTRE_JETON>
Accept: application/json

Ne placez jamais un jeton dans du code versionné. Utilisez un coffre de secrets ou une variable d’environnement.

Ressources exposées

Les familles de ressources suivent la structure du produit :

• sessions : création d’une session assistée, récupération du code à 6 chiffres, état de la session ;
• appareils : liste des agents installés, état en ligne, groupes ;
• audit : lecture des événements du journal chaîné ;
• utilisateurs : techniciens et rôles, sur le plan Business.

Chaque ressource est paginée ; les réponses incluent les identifiants stables à utiliser dans les appels suivants.

Webhooks

Les webhooks (plan Business) poussent les événements vers votre infrastructure au lieu de vous obliger à interroger l’API en continu :

• fin d’une session ;
• connexion ou déconnexion d’un appareil non surveillé ;
• événements d’audit, par exemple un transfert de fichier confirmé.

Un webhook livré ne vaut pas preuve à lui seul : recoupez-le avec le journal d’audit pour les événements sensibles.

Cas d’usage courants

• Automatiser le déploiement : interroger la liste des appareils après un déploiement GPO ou Intune pour vérifier que tout le parc est en ligne. Voir Installer et déployer l’agent.
• Alimenter un ITSM : créer une session assistée depuis votre outil de tickets et récupérer le code à transmettre à l’utilisateur.
• Surveiller : recevoir les événements de session par webhook et les corréler avec votre supervision.

Console ou API ?

Utilisez l’API quand le travail est répétitif ou doit s’intégrer à un autre système : provisionnement, supervision, flux de tickets. Utilisez la console pour le support interactif. Les deux pilotent le même espace : une session créée par l’API apparaît dans la console et inversement.

Exemple : créer une session assistée

POST /v1/sessions
Authorization: Bearer <VOTRE_JETON>
Content-Type: application/json

{ "mode": "attended", "label": "Poste facturation" }

La réponse contient l’identifiant de la session et le code à 6 chiffres à transmettre à l’utilisateur. La requête et son résultat sont consignés dans le journal d’audit, comme toute action de la console.

Bonnes pratiques

• Stockez les jetons dans un coffre de secrets, jamais dans le code.
• Lisez les événements depuis le journal plutôt que d’interroger l’API en continu.
• Testez les webhooks avec un endpoint de test avant la mise en production.
• Révoquez immédiatement le jeton d’un technicien qui quitte l’équipe.

Pour aller plus loin

• Modèle de sécurité et chiffrement : ce que l’API journalise et comment.
• Migrer depuis ScreenConnect : automatiser le redéploiement des agents lors d’une bascule.