Scopes de l'API
Tous les scopes de l'API Servor et ce qu'ils accordent — servers:read, monitors:read, status-pages:read, incidents:read, incidents:write, commands:read et audit:read.
Les scopes déterminent précisément ce qu'un jeton API peut
faire. Vous les choisissez à la création du jeton, et une requête qui exige un
scope absent du jeton renvoie 403. Cette page liste chaque scope proposé par
Servor et ce qu'il accorde, pour garder chaque jeton au moindre privilège.
Lecture d'abord, par conception
L'API publique est une surface de lecture et d'automatisation des incidents. Il n'existe aucun scope d'écriture pour l'infrastructure (serveurs, moniteurs, pages de statut) ni aucune exécution de commande via l'API — ces actions restent dans le tableau de bord. Voir la vue d'ensemble de l'API pour comprendre pourquoi.
La liste complète
Ce sont les seuls scopes qui existent. Tout ce qui n'apparaît pas ici n'est pas disponible.
| Scope | Accorde |
|---|---|
servers:read | Lire vos serveurs — les lister et récupérer le détail d'un serveur. |
commands:read | Lire l'historique des commandes d'un serveur (le journal de ce qui a été exécuté). |
monitors:read | Lire vos moniteurs et leurs vérifications récentes. |
status-pages:read | Lire vos pages de statut, leurs composants et leurs incidents. |
incidents:read | Lister les incidents, en récupérer un et lire sa chronologie de mises à jour. |
incidents:write | Créer des incidents, publier des mises à jour et les résoudre. |
audit:read | Lire le journal d'audit de l'activité de votre équipe. |
Ce que débloque chaque scope
servers:read
Donne l'accès en lecture à l'API Serveurs : lister tous les serveurs de l'équipe et récupérer un serveur par son id. Les réponses ne contiennent jamais d'identifiants SSH ni de données chiffrées. Pour ajouter ou modifier un serveur, passez par le tableau de bord — voir ajouter un serveur.
commands:read
Donne l'accès en lecture à l'historique des commandes d'un serveur — le journal consultable des commandes exécutées. Ce scope est en lecture seule : l'API n'exécute jamais de commande. Pour exécuter quelque chose, utilisez le terminal web ou exécuter des commandes dans le tableau de bord.
monitors:read
Donne l'accès en lecture à l'API Moniteurs : lister vos moniteurs et récupérer les vérifications récentes de l'un d'eux. Pratique pour exporter la disponibilité ou construire vos propres tableaux de bord. Créez les moniteurs dans le tableau de bord — voir créer un moniteur.
status-pages:read
Donne l'accès en lecture à l'API Pages de statut : lister vos pages de statut, lire une page avec ses composants, et lire les incidents qui y sont rattachés. Construisez ou modifiez les pages dans le tableau de bord — voir créer une page de statut.
incidents:read
Donne l'accès en lecture à l'API Incidents : lister
les incidents, en récupérer un et lire sa chronologie complète de mises à jour.
Combinez-le avec status-pages:read pour obtenir les incidents affichés sur une
page précise.
incidents:write
Le seul scope d'écriture. Il permet à un jeton de créer des incidents, de publier
des mises à jour et de les résoudre (publier une mise à jour avec
status=resolved). C'est ce qui rend l'API idéale pour brancher votre propre
système d'alerte sur Servor. Ne l'accordez qu'à un service qui ouvre ou met
réellement à jour des incidents — voir
signaler un incident et
mettre à jour et résoudre. La lecture des
incidents exige toujours incidents:read.
audit:read
Donne l'accès en lecture à l'API Audit — le journal d'activité de votre équipe, y compris l'usage des jetons. Utile pour les exports de conformité et pour surveiller la façon dont vos propres jetons sont utilisés.
Choisir ses scopes
Commencez en lecture seule
N'accordez à un nouveau jeton que les scopes de lecture dont il a besoin, puis
ajoutez incidents:write si — et seulement si — l'intégration doit modifier des
incidents. Un jeton par intégration permet d'en révoquer un seul sans tout casser.
Créez un jeton dans Servor.
Quelques combinaisons courantes :
- Miroir de statut / export de disponibilité —
monitors:read,status-pages:read. - Automatisation d'incidents (ouvrir sur alerte, résoudre au rétablissement) —
incidents:writeplusincidents:readpour réconcilier l'état. - Script d'inventaire / reporting —
servers:read,commands:read,audit:read.
Scopes et rôles d'équipe
Les scopes limitent un jeton ; les rôles
limitent une personne. Un jeton ne peut jamais dépasser ce que l'API expose —
même incidents:write ne peut pas créer de serveur, puisqu'aucun scope d'API ne le
permet. La gestion des jetons est elle-même réservée aux admins, et l'API publique
nécessite le plan AI ; voir plans et limites.