> Ouverture en cours : l'inscription et le paiement ne sont pas encore ouverts à tous. L'état du jour : https://subagent.fr/docs/etat.md > > Pour un agent : la carte du site est sur https://subagent.fr/llms.txt ; chaque page existe en Markdown, à la même adresse suffixée `.md`. # Connecteur pour assistants en ligne > Le connecteur branche l'assistant d'un humain à son espace, sans clé à copier. Son adresse : `https://api.subagent.fr/connect`. L'humain prouve son e-mail par un code à 6 chiffres, choisit son espace et autorise. Sans espace, il ouvre le sien sur la même page. C'est par là qu'il relit et valide les brouillons de son agent. ## Deux adresses, un seul serveur | Adresse | Pour qui | Sans clé ni jeton | |---|---|---| | `https://api.subagent.fr/mcp` | Un agent, avec sa clé `sak_…` dans un en-tête. | Le serveur ne montre qu'un outil : `sign_up`. | | `https://api.subagent.fr/connect` | L'assistant en ligne d'un humain : Claude, ChatGPT, ou tout assistant qui branche un serveur MCP par OAuth. | Le serveur demande une connexion : l'assistant ouvre la page d'autorisation. | Les outils, leurs paramètres et leurs réponses sont les mêmes aux deux adresses. ## Avant de brancher - **Il faut une adresse e-mail**, hors de Subagent : elle reçoit le code de connexion. - **Avec un espace vérifié**, l'humain le retrouve. C'est l'adresse que l'agent a donnée en `human_email`, et qui a reçu le code de vérification. Voir [Démarrer](https://subagent.fr/docs/demarrer.md). - **Sans espace**, l'humain ouvre le sien sur la page de connexion. Il ne faut pas d'agent pour s'inscrire. ## Brancher son assistant 1. **Ajouter le connecteur.** Dans son assistant, l'humain ajoute un connecteur, ou serveur MCP distant, et colle l'adresse `https://api.subagent.fr/connect`. Le geste exact dépend de l'assistant : [Claude](https://subagent.fr/brancher/claude.md), [ChatGPT](https://subagent.fr/brancher/chatgpt.md). 2. **Donner son e-mail.** L'assistant ouvre une page de Subagent. L'humain y indique son adresse. 3. **Saisir le code.** Un code à 6 chiffres part à cette adresse. Il vaut 10 minutes et cinq essais. 4. **Choisir l'espace et autoriser.** La page montre l'application qui demande l'accès, l'adresse où elle repart, l'espace concerné et ce que l'application pourra faire. L'humain autorise, ou refuse. Sans espace, il ouvre le sien : voir ci-dessous. À savoir : - **La page répond la même chose à toute adresse**, qu'elle soit connue ou non. Un code part à l'humain d'un espace vérifié. Il part aussi à une adresse sans espace, dans les limites des inscriptions, et jamais à une boîte de Subagent Mail. - **La demande vaut 15 minutes.** Passé ce délai, il faut la relancer depuis l'assistant. - **Le nom de l'application vient d'elle-même.** Seule l'adresse de retour dit où va l'accès. Quand cette adresse n'est pas celle d'un service reconnu, la page le dit. - **Aucune clé n'est affichée ni copiée.** L'assistant reçoit des jetons, dont le serveur ne garde que l'empreinte. ## Ouvrir un espace sans agent Quand le code est saisi et qu'aucun espace n'est rattaché à l'adresse, la page propose d'en ouvrir un. 1. **Choisir le nom de la première boîte.** L'adresse sera `nom@subagentmail.fr`. Le nom fait 3 à 32 caractères : minuscules, chiffres, point, tiret ou souligné. 2. **Lire ce que l'application pourra faire**, et l'adresse où elle repart. 3. **Choisir « Ouvrir mon espace et autoriser ».** L'espace s'ouvre et l'assistant y est branché, du même geste. - **L'espace s'ouvre déjà vérifié** : le code vient de prouver l'adresse de l'humain. Il n'y a pas de second code. - **Il n'a pas de clé d'agent.** L'assistant y lit et y écrit par le connecteur, avec ce que l'humain a autorisé. - **La boîte reçoit dès son ouverture.** Pour écrire à d'autres que l'humain, il faut un forfait : l'assistant en donne le lien, avec `subscribe`. Voir [Prix et paiement](https://subagent.fr/docs/prix.md). - **Les contrôles sont ceux de `sign_up`** : le format du nom, les noms réservés, les noms déjà pris, les limites d'inscription. La page dit pourquoi un nom est refusé. Voir [Limites](https://subagent.fr/docs/limites.md#inscription). - **Un agent qui travaille seul ouvre son propre espace**, avec `sign_up`, à l'adresse `https://api.subagent.fr/mcp`. Pour avoir un agent et valider depuis son assistant, l'humain laisse l'agent s'inscrire d'abord avec son e-mail, puis retrouve cet espace à la connexion. ## Ce que l'humain accorde La page d'autorisation liste ce que l'application pourra faire, d'après les permissions qu'elle demande. | Permission | Ce que la page en dit | |---|---| | `read` | Lire vos boîtes, vos fils et vos messages. | | `send` | Écrire et répondre depuis vos boîtes, dans les règles d'envoi de l'espace. | | `approve` | Valider ou annuler les brouillons en attente : ce que vous validez dans l'assistant part. | | `manage_inboxes` | Créer et supprimer des boîtes. | Un assistant qui ne demande rien de précis demande les quatre. Avec `approve`, l'humain valide les brouillons (`approve_message`), lève un blocage manuel (`remove_suppression`) et résilie le forfait (`cancel_subscription`). La clé de l'agent ne porte pas cette permission. Voir [Clés et permissions](https://subagent.fr/docs/cles.md#humain). Dans le journal d'un message, l'accès de l'assistant porte le nom de l'application et l'e-mail de l'humain : « Claude (marie@exemple.fr) », par exemple. ## Retirer l'accès L'accès dure tant que l'humain ne le retire pas. Pour y mettre fin, il déconnecte le connecteur dans son assistant. Rebrancher le même assistant reprend la même connexion, avec les permissions du nouveau consentement. ## Ce que dit le serveur à l'agent Un agent n'a pas `approve`. Quand il laisse un brouillon, la réponse lui dit où son humain le valide : ```text Brouillon msg_7f2a91c4e8b34d0fa6c25e1b9d3f7a48 dans le fil thr_0e5a7c2b9f1d48e6a3c7b5d0e2f9a814 : de agent@exemple.fr à nadia.morel@exemple.com, « Rendez-vous de jeudi ». Il attend une validation humaine : votre humain (m•••@exemple.fr) branche son assistant (Claude, ChatGPT…) à l’adresse https://api.subagent.fr/connect, s’y connecte avec cet e-mail, puis relit le brouillon et le valide ou le corrige. Dites-le-lui : aucun avis ne lui est envoyé. Rien ne part avant. ``` Pour un agent : - **Donnez cette adresse à votre humain**, pas la vôtre : `https://api.subagent.fr/mcp` est l'adresse des agents. - **Ne lui demandez ni sa clé ni son code de connexion.** Le code se saisit sur la page de Subagent, pas dans la conversation. - **Prévenez-le vous-même** qu'un brouillon attend : le serveur ne lui envoie aucun avis. Le parcours complet : [Valider les envois d'un agent](https://subagent.fr/docs/guide-validation.md). ## Pour qui construit un client | Sujet | Ce que fait le serveur | |---|---| | Protocole | OAuth 2.1, avec PKCE (`S256`) obligatoire. Les jetons sont opaques. | | Découverte | Sans jeton, `https://api.subagent.fr/connect` répond 401 avec l'adresse de la métadonnée de la ressource (RFC 9728) : `https://api.subagent.fr/.well-known/oauth-protected-resource/connect`. Le serveur d'autorisation se décrit à `https://api.subagent.fr/.well-known/oauth-authorization-server` (RFC 8414). | | Enregistrement | Dynamique (RFC 7591) : `https://api.subagent.fr/oauth/register`. | | Autorisation et jetons | `https://api.subagent.fr/oauth/authorize`, `https://api.subagent.fr/oauth/token`. Types de demande : `authorization_code` et `refresh_token`. | | Révocation | `https://api.subagent.fr/oauth/revoke` (RFC 7009). | | Portées | `send`, `read`, `approve`, `manage_inboxes` : les permissions d'une clé. Voir [Clés et permissions](https://subagent.fr/docs/cles.md#permissions). | | Durées | Un jeton d'accès vaut une heure. Un jeton de renouvellement vaut 30 jours. | Le reste du protocole MCP est celui de `https://api.subagent.fr/mcp` : voir [Serveur MCP](https://subagent.fr/docs/mcp.md).