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, audit:read, metrics:read et scheduled-commands: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.
`metrics:read`	Lire les séries CPU, RAM et disque d'un serveur, pour les tracer ailleurs.
`scheduled-commands:read`	Lire les commandes planifiées d'un serveur et leur dernier résultat.

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.

`metrics:read`

Donne l'accès aux séries de métriques d'un serveur — CPU, RAM, disque — pour les reprendre dans l'outil qui trace déjà vos courbes. Séparé de servers:read à dessein : un jeton qui alimente un graphique n'a aucune raison de lire aussi votre inventaire de machines.

`scheduled-commands:read`

Donne l'accès aux commandes planifiées d'un serveur, leur expression cron et leur dernier résultat — de quoi répondre à « la sauvegarde de cette nuit a-t-elle tourné ? ».

Lire une commande planifiée ne permet pas de la lancer

Aucun jeton ne peut exécuter quoi que ce soit : une exécution doit être signée dans un navigateur avec la clé de votre coffre, que l'API ne détient jamais. Ce scope donne le calendrier et l'historique, jamais le déclencheur.

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:write plus incidents:read pour réconcilier l'état.
Script d'inventaire / reporting — servers:read, commands:read, audit:read.
Alimenter vos propres graphiques — metrics:read seul suffit : il donne les séries sans donner l'inventaire.
Surveiller les tâches planifiées — scheduled-commands:read, éventuellement avec commands:read pour voir aussi ce qui a été lancé à la main.

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.

Voir aussi

Jetons APICréez un jeton et choisissez ses scopes.AuthentificationEnvoyez votre jeton en en-tête Bearer.ErreursPourquoi une requête renvoie 403 et comment y remédier.Rôles et permissionsCe que peut faire chaque rôle d'équipe.