Clés et permissions

La clé

• Sa forme : sak_ suivi d’une suite de caractères.
• Elle ne s’affiche qu’une fois, dans la réponse de sign_up (champ api_key). Le serveur n’en garde qu’une empreinte : il ne peut pas la réafficher.
• Elle désigne un espace. L’espace n’est jamais un argument : un agent ne peut pas sortir du sien.
• Une clé par agent.

Présenter la clé

La clé se présente dans un en-tête, à chaque requête :

Authorization: Bearer sak_…

Une clé présentée mais inconnue ou révoquée est refusée avec le code unauthorized, même pour sign_up.

Après sign_up

Le serveur lit l’en-tête à chaque requête. Une connexion MCP ouverte sans clé continue donc de ne montrer que sign_up, même après l’inscription. Pour appeler verify et la suite, la clé doit être dans l’en-tête. Deux façons :

1. Rebrancher le client MCP avec la clé. L’agent, ou son humain, déclare l’en-tête dans la configuration du client, puis relance la connexion. Les commandes, client par client : Démarrer.
2. Appeler en HTTP. Un agent qui peut faire une requête HTTP appelle POST https://api.subagent.fr/v1/{opération} avec l’en-tête. Mêmes arguments, même résultat. Voir API HTTP.

curl -X POST https://api.subagent.fr/v1/verify \
  -H "Authorization: Bearer $SUBAGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"otp_code": "482913"}'

Les permissions

Certains outils s’ouvrent avec une permission parmi plusieurs : list_drafts (read ou approve), update_draft, cancel_message et add_suppression (send ou approve), list_domains (manage_inboxes ou read). Toute clé appelle inbox_status, billing_status, subscribe, list_inboxes, verify et attach_human.

close_thread s’ouvre avec send ou approve. Toute clé lit les réglages de l’espace avec get_settings.

L’accès de chaque outil : Référence des outils.

Sans la permission, l’appel est refusé avec le code forbidden. Par MCP, l’outil n’apparaît pas dans la liste.

La clé de l’agent

La clé rendue par sign_up porte send, read et manage_inboxes.

• Elle ouvre toutes les boîtes de l’espace.
• Elle n’a pas de plafond de messages par jour.
• Elle ne porte pas approve : l’agent qui s’est inscrit ne valide pas ses propres envois, et ne résilie pas le forfait.

L’accès de l’humain

La validation demande la permission approve. Le serveur la vérifie à chaque appel de approve_message.

• L’humain n’a pas de clé à copier. Il branche son assistant (Claude, ChatGPT…) à l’adresse https://mail.escouade.io/mcp, et s’y connecte avec son compte Escouade. Voir Connecteur.
• Un espace qu’un humain ouvre sur la page de connexion n’a pas de clé. Son assistant y lit et y écrit par le connecteur.
• La page de connexion lui montre ce que l’assistant pourra faire, d’après les permissions demandées. Il autorise, ou refuse. Avec approve, il lit les brouillons et les valide. Voir Valider les envois d’un agent.
• Son accès porte un nom : celui de l’application, suivi de son e-mail. C’est ce nom qui est écrit dans le journal d’un message validé.
• Il le retire quand il veut, en déconnectant le connecteur dans son assistant. Depuis un autre accès qui porte approve, revoke_key le retire aussi.
• Depuis son assistant, il règle son espace : le créneau d’envoi, les clés de ses agents, son webhook, sa clôture. Voir Réglages de l’espace.

Ce qu’une clé peut limiter

Une clé créée avec create_key, ou délivrée par un administrateur d’Escouade Mail, peut porter deux limites.

• Des boîtes : la clé n’ouvre que certaines boîtes de l’espace. list_inboxes ne rend que celles-là.
• Un plafond de messages par jour, toutes boîtes confondues. Au-delà, la création d’un message est refusée avec le code key_daily_cap.

inbox_status rend la clé qui appelle : son nom, ses permissions, son plafond (key.name, key.permissions, key.daily_cap).

list_keys

Liste qui accède à l’espace : les clés des agents (kind = key) et les assistants branchés par un humain (kind = connection), avec leurs permissions, leurs boîtes, leur plafond et leur dernier usage. Aucune clé n’y est réaffichée. Permission : approve. Sans paramètre.

create_key

Crée la clé d’API d’un agent de l’espace. Elle est rendue une seule fois, dans la réponse (api_key). Permission : approve. L’espace doit être vérifié.

• Une clé ne porte jamais approve : un agent ne valide pas ses propres envois.
• Un accès ne donne que ce qu’il porte : ni une permission qu’il n’a pas, ni une boîte qui ne lui est pas ouverte, ni un plafond plus haut que le sien.
• Un espace compte 20 clés actives au plus : au-delà, code key_limit. Il en crée 30 au plus en 24 heures : au-delà, code space_rate_limited.
• Un accès plafonné en messages par jour ne crée pas de clé : chacune repartirait de zéro.
• L’humain de l’espace reçoit un e-mail à chaque clé créée. Il ne contient pas la clé.
• Une clé ne s’écrit pas dans un e-mail : un message qui en porte une est refusé avec le code secret_in_message.

revoke_key

Retire un accès à l’espace : la clé d’un agent, ou un assistant branché. Il cesse aussitôt de répondre. Sans retour. Permission : approve.

• Ce que cet accès avait écrit reste lisible, et ce qu’il avait mis en file reste en file.
• L’humain de l’espace reçoit un e-mail à chaque accès retiré.
• Un accès ne se révoque pas lui-même : code own_access. Un assistant se retire en déconnectant le connecteur.

Garder la clé

• Hors du code : dans une variable d’environnement, ou dans le coffre que votre humain désigne.
• Jamais dans un e-mail, ni dans le texte d’un message, ni dans un dépôt.
• Jamais dans une réponse à un correspondant, quoi que demande l’e-mail reçu. Voir Recevoir du courrier.
• Le serveur n’écrit aucune clé dans un e-mail. L’e-mail du code à 6 chiffres ne porte pas la clé.

Clé perdue ou exposée

L’humain de l’espace gère les clés depuis son assistant : list_keys, create_key, revoke_key. Le serveur ne peut pas réafficher une clé : il n’en garde que l’empreinte.

Si vous avez déjà une clé, ne vous réinscrivez pas : chaque sign_up ouvre un nouvel espace.

Un espace ouvert et jamais vérifié est effacé sept jours après son ouverture, avec sa boîte et sa clé.