Capabilities API

Ce que sont les capabilities#

Chaque clé API porte une liste explicite de capabilities. Une capability est une entrée de liste blanche côté serveur qui désigne quelles opérations /v1/* la clé peut effectuer. Une clé avec desktop:read peut lister et inspecter vos bureaux mais ne peut pas en démarrer un. Une clé avec desktop:lifecycle peut démarrer et arrêter des bureaux mais ne peut pas exécuter de Python dessus. Une clé avec kb:read peut chercher dans votre base de connaissances et rien d'autre.

Restreindre les scopes réduit la surface d'impact. Si une clé fuit -- commitée par accident, copiée dans un carnet partagé, collée dans un chat -- l'attaquant ne peut faire que ce que les capabilities de cette clé autorisent. Par défaut, choisissez le jeu le plus petit possible.

Les capabilities sont statiques#

Les capabilities sont figées à la création de la clé. Il n'existe pas de flux d'édition de clé. Pour changer les scopes, révoquez la clé existante et générez-en une nouvelle avec le bon jeu. C'est volontaire : cela empêche toute escalade silencieuse de privilèges sur une clé déjà distribuée et auditée.

La sélection par défaut#

Le formulaire de création pré-sélectionne un défaut étroit : desktop:read et desktop:chat. C'est suffisant pour qu'un assistant inspecte vos bureaux et discute avec l'agent qui y tourne, sans pouvoir contrôler ni modifier quoi que ce soit. N'ajoutez d'autres scopes que lorsque vous en avez vraiment besoin pour l'intégration que vous montez.

Les scopes utilisateur#

desktop:read#

Lister vos bureaux et lire leurs détails : statut, specs, infos sur l'agent. Pas de contrôle, pas de chat, pas de cycle de vie.

desktop:lifecycle#

Démarrer, arrêter et redémarrer vos bureaux. Ne permet pas de créer de nouveaux bureaux ni d'en détruire -- ces opérations ne sont pas exposées dans cette version.

desktop:control#

Envoyer des entrées souris, clavier et molette à un bureau. Exécuter du Python sur le runtime de l'agent. Prendre des captures d'écran. C'est le scope de contrôle le plus large ; traitez-le comme une credential de bureau distant.

desktop:chat#

Envoyer des messages à l'agent IA qui tourne sur un bureau et recevoir sa réponse. N'inclut ni le contrôle de l'écran, ni le cycle de vie.

scheduled_jobs:read#

Lister les tâches planifiées de votre workspace, éventuellement filtrées par workspace ou par bureau.

scheduled_jobs:write#

Créer des tâches planifiées et déclencher des exécutions immédiates. La suppression de tâches n'est pas exposée dans cette version.

kb:read#

Recherche plein texte et lecture de notes dans la base de connaissances de votre workspace.

Scopes réservés#

Les scopes administrateurs (lecture et écriture) sont réservés pour de futurs outils réservés aux administrateurs et ne peuvent pas être sélectionnés lors de la création d'une clé sur un compte non-administrateur. La création et la suppression de bureaux ne sont pas exposées via l'API dans cette version ; elles auront un scope distinct lorsqu'elles seront introduites.

Forme de l'erreur en cas de capability manquante#

Quand un outil est appelé avec un scope insuffisant, la réponse est 403 Forbidden avec un corps qui nomme la capability manquante ainsi que celles que la clé possède :

{
  "error": "Missing required capability: desktop:lifecycle",
  "required": "desktop:lifecycle",
  "held": ["desktop:read", "desktop:chat"]
}

Utilisez held pour décider s'il faut réessayer avec un autre outil ou émettre une nouvelle clé avec un scope plus large.

Pour la carte complète des capabilities par outil, voir Outils MCP.