Accès API : les jetons de service

Mis à jour le

À quoi sert un jeton de service

Un jeton de service permet à un client de confiance — un tableau de bord mural, un script de supervision — de lire un agrégat de vos cibles sans session de navigateur. Il est en lecture seule : il ne donne accès à aucun écran, à aucune autre partie de l’API, et ne peut rien modifier.

Aujourd’hui, un jeton peut lire une chose : le nombre d’anomalies urgentes (P0 et P1) de vos cibles, et le nom des cibles concernées. Le compte suit celui de votre Inbox : une anomalie prise en charge, reportée ou résolue sort du compte.

Créer un jeton

  1. Ouvrez Paramètres › Accès API. La double authentification doit être activée (Paramètres › Sécurité).
  2. Cliquez sur Nouveau jeton, donnez-lui un nom qui dit où il vit (« Tableau de bord du salon »).
  3. Choisissez son expiration (90 jours au plus).
  4. Limitez-le si possible à l’adresse de votre réseau : le bouton Ajouter mon adresse actuelle la remplit pour vous, si vous créez le jeton depuis le réseau où il servira.
  5. Confirmez avec votre mot de passe et un code de votre application d’authentification.

Le jeton s’affiche une seule fois. Copiez-le dans la configuration du client, jamais dans un dépôt de code ni dans un message.

Appeler l’API

Le jeton se passe dans l’en-tête Authorization, en HTTPS, jamais dans l’URL :

curl -H "Authorization: Bearer $STATHALL_TOKEN" \
  https://app.stathall.com/api/v1/service/anomalies/urgentes

{"p0": 2, "p1": 5, "cibles": [{"nom": "ComploDex iOS", "p0": 1, "p1": 2}]}

Une lecture toutes les deux minutes suffit largement. La liste s’arrête à vingt cibles, triées par P0 puis P1 ; les totaux couvrent toutes vos cibles.

Une requête refusée répond toujours de la même façon, sans dire pourquoi : le détail est dans le journal du jeton (bouton Détails).

Ce qui vous prévient

Vous recevez un message Telegram (si vous avez branché un canal Telegram) et un e-mail :

  • à la création et à la régénération d’un jeton ;
  • au premier usage depuis une nouvelle adresse ;
  • quand un jeton révoqué, expiré ou suspendu est encore présenté, ou depuis une adresse hors de sa liste ;
  • une semaine puis la veille de l’expiration.

Un jeton est suspendu automatiquement s’il est utilisé de façon anormale (volume excessif, plusieurs réseaux nouveaux en peu de temps) ou s’il est vu dans une URL ou envoyé sans HTTPS. Dans ces deux derniers cas, il doit être considéré comme publié : régénérez-le.

Régénérer, révoquer

Régénérer crée un nouveau jeton avec les mêmes réglages ; l’ancien reste valable le temps choisi (24 heures par défaut) pour que vous déployiez le nouveau sans coupure.

Révoquer prend effet immédiatement, dès la requête suivante. Désactiver la double authentification révoque tous vos jetons de service.