Portées

Une portée dit ce qu’une clé d’API peut faire. Une clé porte une ou plusieurs portées ; chaque route de l’API en exige exactement une ; la requête passe quand l’une des portées de la clé couvre celle qui est exigée. Les portées restreignent : une clé ne fait jamais plus que le membre qui l’a créée (Authentification).

La grammaire

Une portée s’écrit <domaine>:<verbe>, le verbe étant read, write ou * :

• workflows:read — lire les routes du domaine ;
• workflows:write — lire et écrire : write implique read. Une clé qui peut créer un workflow peut le relire ; une clé qui écrirait à l’aveugle n’aiderait personne ;
• workflows:* — le joker d’un domaine, équivalent à write aujourd’hui et à ce que le domaine gagnera demain.

Il n’existe pas de joker global : une clé qui peut tout est une clé qu’on ne sait plus révoquer sans tout couper. Accordez un domaine à la fois.

Une route exige un verbe précis, jamais un joker : GET /api/v1/workflows exige workflows:read, POST /api/v1/workflows exige workflows:write. C’est la clé qui peut porter une portée plus large. À la création d’une clé, les portées redondantes sont réduites : demander workflows:read et workflows:write n’enregistre que workflows:write.

Le verbe suit l’effet de la route, pas sa méthode HTTP. Faire tourner un workflow crée une exécution : POST /api/v1/workflows/{id}/test, POST /api/v1/workflows/{id}/run et les routes de rejeu exigent executions:write, pas workflows:write.

Les domaines

Les domaines sont ceux de l’écran Réglages › Clés d’API, où chacun est une ligne à trois choix : rien, lire, lire et écrire.

Domaine	Ce qu’il couvre
workflows	Workflows (brouillons, versions, publication, catalogue de nœuds), runs d’évaluation de prompt, installation d’un template
executions	Exécutions (lire, rejouer, annuler, essais), exécutions en attente et leur réveil à la main
mailboxes	Boîtes (liste, synchronisation, journal, dossiers)
messages	Messages (lire, chercher, envoyer, brouillons), fils et leurs actions
tables	Tables (schéma et lignes)
contacts	Carnet
templates	Templates de workflows (lire le catalogue ; en installer un relève de workflows:write)
connections	Connexions (intégrations, modèles d’IA)
approvals	Approbations
notifications	Notifications et incidents, résumé des exécutions compris
review	Revue du matin et journal d’envoi
analyzer	Analyseur de boîte
assistant	Assistant de workflows
dashboard	Tableau de bord
profile	Mon compte (profil, périmètre, signatures)
admin	Administration (membres, politiques, journal d’audit), réservé aux administrateurs

La portée exacte de chaque route est dans la référence, sous sa ligne Accès.

Les portées réservées aux administrateurs

admin:read, admin:write et admin:* ne peuvent être posées sur une clé que par un administrateur. Ce n’est pas une mesure de sécurité (la clé d’un membre ordinaire échouerait de toute façon au contrôle d’administrateur) mais une question d’honnêteté : une portée qu’on peut cocher et qui ne fera jamais rien est un mensonge d’écran. POST /api/v1/api-keys les refuse à un membre ordinaire avec api_key.scope_forbidden.

À l’inverse, la clé d’un administrateur sans portée admin n’atteint pas /api/v1/admin/… : la clé restreint, comme toujours.

signals:write

signals:write est la seule portée sans pendant read : un signal s’émet, il ne se lit pas. Elle couvre une route, POST /api/v1/signals, qui réveille ou annule les exécutions en attente d’une clé de signal (voir le nœud flow.wait). C’est la portée à donner à un CRM ou à un service de signature qui a seulement besoin de dire à Mankomail « ce dossier est signé ».

Comment une route déclare sa portée

Dans le document OpenAPI, chaque route ouverte aux clés porte l’extension x-required-scope, et liste la même portée dans son exigence security :

{
  "summary": "Créer un workflow",
  "x-required-scope": "workflows:write",
  "security": [
    { "sessionCookie": [] },
    { "apiKey": ["workflows:write"] }
  ]
}

Les deux entrées de security sont des alternatives : un cookie de session, ou une clé d’API dont les portées couvrent workflows:write. Les routes réservées à la session ne portent que sessionCookie ; les routes publiques portent un security vide.

Quand une portée manque

Une clé dont les portées ne couvrent pas la route reçoit 403 avec le code api_key.scope_missing et la portée à ajouter dans details.required :

{
  "code": "api_key.scope_missing",
  "message": "missing scope workflows:write",
  "details": { "required": "workflows:write" }
}

La clé elle-même va bien. Créez une clé avec la portée manquante (ou un verbe plus large sur le même domaine) et remplacez-la dans le système appelant. Les portées ne se modifient pas après la création.