Capabilities API

Ce que sont les capabilities#

Chaque cle API porte une liste explicite de capabilities. Une capability est une entree de liste blanche cote serveur qui designe quelles operations /v1/* la cle peut effectuer. Une cle avec desktop:read peut lister et inspecter vos bureaux mais ne peut pas en demarrer un. Une cle avec desktop:lifecycle peut demarrer et arreter des bureaux mais ne peut pas executer de Python dessus. Une cle avec kb:read peut chercher dans votre base de connaissances et rien d'autre.

Restreindre les scopes reduit la surface d'impact. Si une cle fuit -- commitee par accident, copiee dans un carnet partage, collee dans un chat -- l'attaquant ne peut faire que ce que les capabilities de cette cle autorisent. Par defaut, choisissez le jeu le plus petit possible.

Les capabilities sont statiques#

Les capabilities sont figees a la creation de la cle. Il n'existe pas de flux d'edition de cle. Pour changer les scopes, revoquez la cle existante et generez-en une nouvelle avec le bon jeu. C'est volontaire : cela empeche toute escalade silencieuse de privileges sur une cle deja distribuee et auditee.

La selection par defaut#

Le formulaire de creation pre-selectionne un defaut etroit : 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 controler ni modifier quoi que ce soit. N'ajoutez d'autres scopes que lorsque vous en avez vraiment besoin pour l'integration que vous montez.

Les scopes utilisateur#

desktop:read#

Lister vos bureaux et lire leurs details : statut, specs, infos sur l'agent. Pas de controle, pas de chat, pas de cycle de vie.

desktop:lifecycle#

Demarrer, arreter et redemarrer vos bureaux. Ne permet pas de creer de nouveaux bureaux ni d'en detruire -- ces operations ne sont pas exposees dans cette version.

desktop:control#

Envoyer des entrees souris, clavier et molette a un bureau. Executer du Python sur le runtime de l'agent. Prendre des captures d'ecran. C'est le scope de controle le plus large ; traitez-le comme une credential de bureau distant.

desktop:chat#

Envoyer des messages a l'agent IA qui tourne sur un bureau et recevoir sa reponse. N'inclut ni le controle de l'ecran, ni le cycle de vie.

scheduled_jobs:read#

Lister les taches planifiees de votre workspace, eventuellement filtrees par workspace ou par bureau.

scheduled_jobs:write#

Creer des taches planifiees et declencher des executions immediates. La suppression de taches n'est pas exposee dans cette version.

kb:read#

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

Scopes reserves#

Les scopes administrateurs (lecture et ecriture) sont reserves pour de futurs outils reserves aux administrateurs et ne peuvent pas etre selectionnes lors de la creation d'une cle sur un compte non-administrateur. La creation et la suppression de bureaux ne sont pas exposees 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 appele avec un scope insuffisant, la reponse est 403 Forbidden avec un corps qui nomme la capability manquante ainsi que celles que la cle possede :

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

Utilisez held pour decider s'il faut reessayer avec un autre outil ou emettre une nouvelle cle avec un scope plus large.

Pour la carte complete des capabilities par outil, voir Outils MCP.