Portées API et autorisations des forfaits

Les portées déterminent exactement ce qu'un jeton API peut faire. Chaque jeton contient un ensemble de portées, que l'API vérifie à chaque requête.

Fonctionnement des portées

Lorsque vous créez un jeton, vous sélectionnez les portées à inclure. L'API applique trois plafonds à chaque requête :

1. Droits du compte : le forfait actuel et les modules actifs déterminent les fonctionnalités disponibles.
2. Adhésion : une personne déléguée ne peut pas accorder ni utiliser plus que ce que permettent son rôle et son accès aux domaines actuels.
3. Autorisation des identifiants : le jeton ou le consentement OAuth doit inclure la portée requise par l'endpoint.

L'erreur indique le plafond qui a échoué. insufficient_scope signifie que la portée n'a jamais été accordée aux identifiants, scope_blocked_by_membership que le rôle de la personne est plus restreint et scope_blocked_by_entitlement que le droit White Label requis n'est pas actif.

Deux couches de portées : OAuth et portées API

OAuth prend en charge six ensembles pratiques historiques, chaque portée API détaillée et les sélecteurs tools:* qui contrôlent uniquement l'exposition. Les ensembles historiques sont :

Chaque ensemble OAuth historique se développe en portées API détaillées, telles que domains:read et drive:account:write. Les nouvelles intégrations peuvent demander directement ces portées granulaires. Les portées White Label sont volontairement absentes des anciens ensembles mail:*, afin qu'un connecteur existant n'obtienne jamais l'administration revendeur après une mise à niveau. Il doit demander explicitement les portées White Label nécessaires. Un sélecteur tools:white_label limite l'exposition MCP, mais n'accorde à lui seul aucune autorisation API.

Trois modes de connexion et leurs capacités

Un agent ou une intégration peut accéder à TrekMail de trois façons, et le mécanisme de contrôle diffère pour chacune. C'est important, car les « indicateurs de capacité » MCP (TREKMAIL_ALLOW_DESTRUCTIVE, TREKMAIL_ALLOW_SENDING, TREKMAIL_ALLOW_MIGRATION) n'existent que dans l'une d'elles.

En bref : MCP HTTP hébergé filtre les outils annoncés selon l'identifiant OAuth; MCP stdio croise les portées du jeton avec les ensembles d'outils, le mode lecture seule et les contrôles de sécurité locaux; l'API REST est contrôlée directement par les portées granulaires du jeton. L'autorisation API à l'exécution reste déterminante dans chaque mode.

Référence des portées

Compte et facturation

billing:autopay est la seule portée qui déplace de l'argent, il vaut donc la peine de la lire deux fois.

Elle est volontairement séparée de billing:read : une connexion autorisée à voir votre facture ne doit pas pouvoir l'augmenter, et accorder la lecture de la facturation ne vaut pas consentement à dépenser. Elle n'est jamais incluse automatiquement; un jeton ou une connexion ne la possède que si vous l'avez explicitement accordée, et elle est absente de chacun des anciens ensembles généraux de portées. Une connexion autorisée avant son existence ne peut donc rien dépenser.

Ce qu'elle permet : acheter des crédits de vérification d'e-mails et démarrer un abonnement. Ce qu'elle ne permet absolument pas : annuler, rétrograder ou modifier un abonnement existant. Ces actions n'ont aucun endpoint. Les dépenses sont aussi plafonnées par achat, par jour et par mois pour l'ensemble du compte, quel que soit le nombre de connexions qui possèdent la portée.

Elle est disponible avec tous les forfaits, car les crédits de vérification sont vendus avec chacun d'eux, y compris Nano.

Domaines

La distribution par alias de domaine commence avec Starter. Les jetons Starter peuvent lire l'état enregistré et réel; connecter, modifier ou supprimer cet alias via API/MCP nécessite la capacité domains:write de Pro/Agency. Les modifications restent disponibles dans le tableau de bord avec Starter. Consultez Alias de domaine via API et MCP.

White Label

Ces portées de jetons opérationnels apparaissent uniquement pendant qu'un essai ou module payant White Label est actif. Pendant le délai de grâce d'annulation, le propriétaire conserve les portées de lecture; les membres délégués et toutes les portées d'écriture sont supprimés.

L'adhésion actuelle applique un autre plafond. Un client ou coéquipier ne peut jamais élargir son propre rôle, accès aux domaines ou autorisations personnalisées en créant un jeton plus large. Consultez Gérer les équipes White Label avec API et MCP.

Boîtes mail

Messages (jeton de message)

Les portées de messages sont portées par des jetons de message (préfixe tm_msg_), et non par des jetons opérationnels (préfixe tm_live_). Les jetons de message sont créés via l'API avec un jeton opérationnel possédant la portée mailboxes:message-tokens:manage. Ils ont des protections propres à l'API en plus des limites ordinaires d'envoi : par défaut, la lecture autorise 30 requêtes par minute et 5,000 lectures réussies par jour et par jeton; l'envoi autorise 60 requêtes par minute et par jeton, et 100 envois API quotidiens pour la boîte. Un second compteur de sécurité est fixé par défaut à 500 envois par jour, donc le plafond inférieur de la boîte s'applique normalement.

Tous les nouveaux endpoints de l'API webmail (contacts, calendrier, identités, modèles, expéditeurs bloqués, brouillons, envoi programmé, dossiers, pièces jointes) correspondent aux trois portées de messages existantes; aucune nouvelle portée n'a été ajoutée. Les jetons existants continuent de fonctionner sans modification.

messages:read n'accorde pas d'accès en écriture. Dans OAuth hébergé, approuver la capacité plus large messages:send fournit ensemble les accès en lecture, écriture et envoi; un jeton tm_msg_ créé manuellement conserve exactement les portées choisies lors de sa création.

Tickets d'assistance

Starter : lecture seule via API. Ouvrez les tickets et répondez-y depuis le tableau de bord.

Configuration SMTP

SMTP est configuré par domaine (/api/v1/domains/{id}/smtp), avec une seule valeur par défaut pour le compte (/api/v1/smtp/default) qui détermine le réglage initial des nouveaux domaines. Consultez Présentation de l'API pour la liste complète des endpoints. Les anciens endpoints de compte /api/v1/smtp répondent encore pour la rétrocompatibilité, mais ne contrôlent plus le routage.

Migrations

Les portées de migration sont portées par des jetons opérationnels (préfixe tm_live_). Starter peut consulter les migrations via l'API et les exécuter depuis le tableau de bord. Pro et Agency peuvent aussi les démarrer, annuler, réessayer et supprimer via l'API et MCP.

Cloudflare

Drive

Les portées Drive sont des portées de jetons opérationnels. Un jeton peut être limité à certaines boîtes mail, et Drive lui masquera les autres espaces. L'achat, le redimensionnement et l'annulation du module Drive ne sont pas des opérations d'écriture API/MCP; les changements de facturation restent dans le tableau de bord.

Nano + module Drive : avec un module Drive Storage actif, Nano obtient toutes les portées Drive. Rien d'autre n'est débloqué, seulement Drive et les portées Email Verifier que Nano possède déjà. Si vous annulez le module, les portées de lecture restent actives pendant le délai de grâce de 7 jours pour terminer vos téléchargements ou votre transition; l'écriture, le partage et la purge sont coupés immédiatement.

Email Verifier

Les portées Email Verifier sont disponibles avec tous les forfaits, y compris Nano. La seule limite est votre solde de crédits. Consultez API Email Verifier pour la référence complète des endpoints.

Niveaux d'accès des forfaits

Les portées White Label s'ajoutent au forfait de base Pro ou Agency au lieu d'en faire partie. Elles apparaissent pour ces comptes uniquement lorsque leur droit White Label est actif.

Conséquences d'une rétrogradation

Si vous passez de Pro à Starter, les jetons existants dotés de portées d'écriture ne sont pas supprimés. L'API bloque plutôt à l'exécution les requêtes utilisant des portées interdites.

Par exemple, un jeton avec mailboxes:create sur Starter reçoit 403 avec le code token_scope_blocked_by_plan lorsqu'il tente de créer une boîte mail. Les portées de lecture du même jeton continuent de fonctionner.

Pour corriger cela, révoquez l'ancien jeton et créez-en un nouveau avec seulement les portées permises par votre forfait actuel.

Portées dangereuses

Les portées mailboxes:delete, domains:delete, migrations:write et cloudflare:delete sont signalées comme dangereuses dans le tableau de bord. Leurs jetons peuvent lancer la suppression de boîtes ou de domaines, retirer des jetons Cloudflare ou effectuer d'autres actions irréversibles. Vérifiez si votre cas d'usage les exige réellement.

Pour un serveur MCP hébergé localement, l'administrateur peut exiger TREKMAIL_ALLOW_DESTRUCTIVE=true avant de rendre disponibles les outils de suppression. MCP hébergé utilise les portées approuvées pendant OAuth.

La portée messages:send permet d'envoyer de vrais e-mails depuis la boîte. Sur un serveur MCP hébergé localement, l'envoi peut aussi exiger TREKMAIL_ALLOW_SENDING=true et confirm_send=true à chaque appel. Consultez Garde-fous et intentions de suppression pour plus de détails.

La portée migrations:write permet de lancer des migrations d'e-mails qui se connectent à des serveurs IMAP externes avec des identifiants enregistrés. Sur un serveur MCP hébergé localement, les écritures de migration peuvent aussi exiger TREKMAIL_ALLOW_MIGRATION=true et des paramètres de confirmation par appel (confirm_start, confirm_cancel, confirm_retry).

Contraintes de domaine

Les portées contrôlent ce qu'un jeton peut faire. Les contraintes de domaine contrôlent où il peut le faire.

Un jeton limité à des domaines précis voit et modifie uniquement les ressources de ces domaines. Cela permet de donner à un prestataire ou agent l'accès à un seul domaine client sans exposer les autres.

Les contrôles de portée ont lieu avant ceux des contraintes de domaine. Si un jeton ne possède pas la portée requise, la requête échoue avec 403, quelles que soient les contraintes.

Solutions rapides

• 403 "insufficient_scope" : votre jeton n'a pas la portée requise par cet endpoint. Créez un nouveau jeton avec les bonnes portées.
• 403 "token_scope_blocked_by_plan" : votre forfait ne permet plus une ou plusieurs portées du jeton. Changez de forfait ou révoquez le jeton et créez-en un avec les portées permises.
• 403 "scope_blocked_by_entitlement" : White Label est inactif ou une écriture a été tentée pendant le délai de grâce d'annulation. Réactivez-le avant de réautoriser la connexion.
• 403 "scope_blocked_by_membership" : le rôle actuel du membre ou l'autorisation personnalisée ne permet pas l'action. Demandez au propriétaire de modifier cette adhésion.
• Certaines portées sont masquées dans le formulaire de création : votre forfait ne les prend pas en charge. Seules les portées permises sont affichées.

Articles associés

• Présentation de l'API
• Créer et gérer des jetons API
• Garde-fous et intentions de suppression
• Présentation des forfaits TrekMail