Création et gestion des jetons API

Les jetons API déterminent ce qu'une application ou un agent peut faire sur votre compte. Chaque jeton possède un nom, des autorisations, des restrictions de domaine facultatives et une date d'expiration.

Vous connectez un client MCP? S'il prend en charge l'autorisation par navigateur, ajoutez https://trekmail.net/mcp comme serveur MCP distant et approuvez l'accès dans le navigateur. En général, vous n'avez pas besoin de créer ni de coller un jeton. Les jetons tm_live_ manuels servent aux scripts, aux tâches CI, aux serveurs MCP auto-hébergés et aux clients qui ne prennent pas en charge ce flux. Consultez Connecter des agents IA (MCP).

Avant de commencer

• Toutes les offres peuvent créer des jetons API, y compris Nano. Les offres Nano sont limitées aux autorisations Email Verifier (verify:read, verify:write).
• Les offres Starter permettent des autorisations d'infrastructure en lecture seule, ainsi que toutes les autorisations Drive et Email Verifier. Starter peut aussi gérer le transfert dans le tableau de bord, mais l'accès en écriture au transfert par API (mailboxes:forwarding:write) exige Pro ou Agency. Pro et Agency donnent accès à toutes les autorisations.
• Le propriétaire peut gérer tous les identifiants du compte. Un membre délégué autorisé à gérer les jetons API ne peut gérer que les identifiants qu'il a créés, et n'accorder que les autorisations et domaines déjà inclus dans son adhésion.
• Conseil: Cliquez sur Démarrer la visite sur la page Agents IA et API pour découvrir rapidement les options de connexion, les jetons, les applications connectées et le journal d'audit.

Créer un jeton d'automatisation Drive

L'API Drive et les outils MCP utilisent des jetons d'opérations (tm_live_...). Sélectionnez uniquement les autorisations Drive nécessaires au flux de travail:

• Rapports en lecture seule: drive:account:read, drive:mailbox:read ou drive:addon:read.
• Automatisation des téléversements: ajoutez drive:account:write ou drive:mailbox:write.
• Liens publics de diffusion: ajoutez drive:account:share ou drive:mailbox:share.
• Nettoyage permanent: utilisez drive:account:purge ou drive:mailbox:purge uniquement dans un jeton distinct et étroitement contrôlé.

L'achat, le redimensionnement et la résiliation du module Drive ne sont pas accessibles au moyen des jetons API. Les agents peuvent lire l'état et le prix du module avec drive:addon:read, mais les changements d'abonnement restent dans le tableau de bord.

Créer un jeton d'automatisation White Label

White Label utilise cinq autorisations de jeton d'opérations: branding:read, branding:write, members:read, members:write et activity:read. Elles apparaissent uniquement lorsque le compte dispose de White Label. members:write est marquée comme dangereuse, car elle peut supprimer un accès et révoquer les clés d'une autre personne.

Pour une intégration d'état et d'audit en lecture seule, sélectionnez branding:read, members:read et activity:read. Ajoutez branding:write uniquement pour la configuration de la marque et du DNS. Ajoutez members:write seulement lorsque l'automatisation doit inviter ou modifier des personnes.

Pendant le délai de grâce de résiliation, le propriétaire conserve les trois autorisations de lecture pour la récupération, tandis que les écritures et les identifiants White Label délégués cessent de fonctionner. La réactivation ne rétablit pas un identifiant révoqué; créez-en ou autorisez-en un nouveau.

Créer un jeton

1. Accédez à Agents IA et API → Jetons.
2. Cliquez sur Créer un jeton.
3. Remplissez le formulaire:
   • Nom: Libellé permettant d'identifier le jeton (par exemple, «Agent Claude», «Pipeline CI/CD»).
   • Expiration: Choisissez 7 jours, 30 jours, 90 jours, une date personnalisée ou aucune expiration.
   • Autorisations: Sélectionnez les opérations que le jeton peut effectuer. Toutes les autorisations permises sont cochées par défaut.
   • Restriction de domaine: Choisissez «Tous les domaines» ou sélectionnez certains domaines pour limiter l'accès du jeton.
4. Cliquez sur Créer un jeton.

Après la création, le jeton en texte brut est affiché une seule fois. Copiez-le immédiatement ou utilisez le bouton Télécharger pour l'enregistrer dans un fichier .txt.

Le jeton ne pourra plus être affiché. Enregistrez-le en lieu sûr avant de fermer la confirmation.

Créer un jeton de message

Les jetons de message permettent aux agents de lire et d'envoyer des e-mails depuis une boîte précise. Ils sont distincts des jetons d'opérations et sont créés par programmation au moyen de l'API avec votre jeton d'opérations.

Pour créer un jeton de message, votre agent appelle:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Choisissez les autorisations minimales nécessaires au flux de travail:

Le jeton en texte brut (tm_msg_...) est renvoyé une seule fois. Ajoutez-le à votre configuration MCP sous le nom TREKMAIL_MESSAGE_TOKEN.

Les jetons de message sont disponibles avec les offres Pro et Agency. Le jeton d'opérations doit disposer de l'autorisation mailboxes:message-tokens:manage.

Pour une boîte Gmail connectée ou une autre boîte externe, utilisez external_account_id. Pour que les destinataires voient plutôt une adresse professionnelle autorisée, utilisez également un identity_id renvoyé par l'endpoint des identités. Consultez Adresses d'envoi via API et MCP.

Format des jetons

TrekMail utilise deux préfixes pour distinguer les types de jetons:

Les 8 premiers caractères après le préfixe sont conservés sous la forme d'un préfixe visible dans le tableau de bord afin de faciliter l'identification.

Autorisations

Les autorisations déterminent ce que le jeton peut faire. Les options disponibles dépendent de votre offre:

• Nano: Email Verifier uniquement (verify:read, verify:write). L'ajout de Drive Storage donne également au compte les fonctions API Drive et MCP auxquelles il a droit.
• Starter: Accès complet à Drive et Email Verifier, et accès en lecture seule à tout le reste (domaines, boîtes, transfert, filtres de courrier, réponse automatique, migrations, tickets, SMTP, Cloudflare). Utilisez le tableau de bord pour les actions d'écriture que Starter ne propose pas par API, comme créer des migrations, répondre aux tickets ou modifier la réponse automatique.
• Pro et Agency: Accès complet. Lecture, écriture, création et suppression pour toutes les familles, ainsi que jetons de message pour lire et envoyer des e-mails par API.

Les autorisations White Label correspondent au droit du module complémentaire et ne permettent pas de contourner le tableau des offres. Elles sont proposées uniquement lorsque White Label est actif; le propriétaire conserve un accès de récupération en lecture seule pendant le délai de grâce de résiliation.

Consultez Autorisations API et offres pour obtenir la référence de chaque autorisation.

Restrictions de domaine

Par défaut, les jetons peuvent accéder à tous les domaines de votre compte. Pour limiter un jeton à certains domaines:

1. Sélectionnez Domaines sélectionnés dans la section de restriction de domaine.
2. Cochez les domaines auxquels le jeton doit accéder.

Un jeton restreint reçoit des réponses 404 lorsqu'il tente d'accéder aux ressources d'autres domaines; l'API se comporte comme si ces domaines n'existaient pas.

Révoquer un jeton

1. Accédez à Agents IA et API → Jetons.
2. Repérez le jeton dans la liste.
3. Cliquez sur Révoquer.
4. Confirmez la révocation.

Les jetons révoqués cessent immédiatement de fonctionner. Toute requête API utilisant un jeton révoqué reçoit 401 Unauthorized.

La révocation est définitive et ne peut pas être annulée. Créez un nouveau jeton si vous devez rétablir l'accès.

État du jeton

Les jetons ont trois états:

Utilisez le filtre d'état de la page Jetons pour afficher les jetons par état.

Journal d'audit

Chaque création et révocation de jeton apparaît dans l'onglet Journal d'audit. Les événements incluent le nom du jeton, l'action et l'heure.

Solutions rapides

• «Autorisations indisponibles avec votre offre»: Votre offre ne comprend pas ces autorisations. Nano reste limité à verify:read et verify:write (ajoutez le module Drive Storage pour obtenir également les autorisations drive:*). Starter ajoute l'accès en lecture à toutes les familles d'infrastructure, ainsi que Drive et Email Verifier complets. Pro et Agency permettent l'écriture partout.
• Jeton en texte brut perdu: Le jeton ne peut pas être récupéré. Révoquez-le et créez-en un nouveau.
• Le jeton fonctionne, mais renvoie 404 pour certains domaines: Il possède probablement une restriction de domaine. Révoquez-le et recréez-le avec «Tous les domaines», ou ajoutez les domaines manquants à la restriction.
• Une autorisation White Label renvoie scope_blocked_by_entitlement: Réactivez White Label, puis créez ou autorisez un identifiant avec l'autorisation requise.
• Un jeton délégué s'est arrêté après un changement de rôle: La réduction, la suspension ou la suppression de l'accès d'un membre révoque immédiatement les identifiants concernés. Créez un nouveau jeton une fois que le propriétaire a restauré l'accès approprié.

Articles associés

• Présentation de l'API Drive
• Présentation de l'API
• Autorisations API et offres
• Connecter des agents IA (MCP)
• Gérer les équipes White Label avec API et MCP