Authentification

Lancez openemail login dans un terminal et elle vous demande laquelle vous voulez. Dans les deux cas, la connexion est enregistrée comme profil, et chaque commande suivante utilise le profil actif.

• —Seule une connexion par navigateur peut utiliser ai compose, ai summarize et les commandes MCP.
• —Une connexion par navigateur dure jusqu'à l'expiration de l'approbation choisie, ou jusqu'à votre déconnexion. Une clé fonctionne jusqu'à sa révocation.

1. 1openemail login enregistre une nouvelle application pour cette connexion, nommée OpenEmail CLI on <your computer>, et ouvre la page d'approbation d'OpenEmail dans votre navigateur. Si le navigateur ne s'ouvre pas, utilisez le lien qu'elle affiche.
2. 2Connectez-vous si besoin, puis choisissez l'espace de travail, l'accès de la CLI (lecture, lecture et envoi, complet, ou votre propre ensemble de permissions), les domaines ou adresses qu'elle atteint, et la durée de l'approbation.
3. 3Approuvez. Le navigateur renvoie l'approbation au terminal de lui-même, et vous pouvez fermer l'onglet. La CLI affiche sous quelle identité vous êtes connecté, l'espace de travail et la date d'expiration de l'approbation.

openemail loginopenemail login --scopes emails:send,threads:readopenemail login --profile work

• —La CLI attend votre approbation pendant 10 minutes. Choisir Pas maintenant sur la page d'approbation annule la connexion, avec le code de sortie 10.
• —--scopes présélectionne des permissions sur la page d'approbation, et vous pouvez encore les modifier là.
• —Quand le profil contient déjà une connexion, un terminal demande avant de la remplacer. Sans surveillance, il refuse, sauf si vous passez --force ou --yes. Remplacer une connexion par navigateur révoque l'ancienne.

Dessous se trouve le flux OAuth qu'utilise le serveur MCP : un client public avec PKCE, un code à usage unique et un jeton d'accès valable une heure et renouvelé pour vous. Le navigateur revient vers 127.0.0.1 sur un port aléatoire, et seul le code de cette connexion y est accepté.

Quand la CLI ne peut pas ouvrir de navigateur sur cette machine, elle affiche le lien à la place : par SSH, en CI, sous Linux sans affichage, ou quand vous passez --no-browser. Ouvrez le lien dans un navigateur sur n'importe quel appareil et approuvez. La page affiche alors un code de connexion, que vous collez dans le terminal.

$ openemail login --no-browserOpen this link in a browser on any device to sign in:  https://api.openemail.uk/auth/mcp/authorize?response_type=code&client_id=…Paste the code from your browser

• —Un code ne vaut que pour la connexion qui a affiché le lien, donc un code venu d'un autre onglet est refusé.
• —Coller l'adresse complète où le navigateur a abouti fonctionne aussi.
• —Sans terminal, envoyez le code sur stdin.

Une clé API connecte un script sans navigateur et ne se voit jamais demander de code. Créez-en une dans Paramètres → Clés API (openemail open api-keys) avec seulement les scopes dont le script a besoin. La CLI vérifie la clé avec GET /keys/self avant de l'enregistrer, et accepte les clés oe_live_ et oe_test_. Le courrier envoyé avec une clé de test n'est jamais distribué.

openemail login --with-token < ~/.config/openemail/keyecho "$OPENEMAIL_KEY" | openemail login --with-token --profile ciopenemail login --token oe_live_…

--token fonctionne aussi, mais la clé atterrit dans l'historique de votre shell, donc la CLI vous avertit et suggère --with-token. Deux façons utilisent une clé sans l'enregistrer :

• —OPENEMAIL_API_KEY dans l'environnement est utilisée par chaque commande qui la voit, avant tout profil enregistré.
• —--api-key <key> est utilisée pour cette seule commande.

Quand il y a plus d'un identifiant, le premier de ceux-ci l'emporte : --api-key, OPENEMAIL_API_KEY, le profil nommé par --profile, le profil nommé par OPENEMAIL_PROFILE, puis le profil actif.

Un profil est une connexion enregistrée, de l'un ou l'autre type. Le premier s'appelle default. Connectez-en d'autres avec --profile, et passez de l'un à l'autre :

openemail login --profile workopenemail profile listopenemail profile use workopenemail inbox --profile defaultOPENEMAIL_PROFILE=work openemail statusopenemail profile currentopenemail profile remove work

• —profile list montre chaque profil avec son type, son espace de travail et son utilisateur ou sa clé, et marque le profil actif. Son JSON n'inclut jamais de jeton ni de clé.
• —profile current n'affiche que le nom sur stdout, donc $(openemail profile current) fonctionne dans un script.
• —profile remove <name> équivaut à openemail logout --profile <name>.
• —Un nom de profil compte jusqu'à 64 lettres, chiffres, points, tirets et tirets bas.
• —profile use s'appelle aussi profile switch. Retirer le profil actif, ou s'en déconnecter, ne laisse aucun profil actif, et la commande suivante qui a besoin d'une connexion renvoie vers openemail profile use <name>.

Un profil enregistré retient l'API à laquelle il s'est connecté, et son identifiant n'est jamais envoyé ailleurs. Un --base-url ou OPENEMAIL_BASE_URL qui nomme une autre origine arrête la commande avec le code de sortie 2 avant tout envoi, et explique comment se connecter à cette origine avec un profil à part.

openemail login --profile other --base-url https://api.example.comopenemail inbox --profile other

• —Une clé venant de OPENEMAIL_API_KEY ou de --api-key n'est pas un profil enregistré : elle va donc vers l'origine de --base-url ou de OPENEMAIL_BASE_URL, ou vers https://api.openemail.uk quand aucun des deux n'est défini.
• —Les commandes qui n'envoient aucun identifiant suivent --base-url et OPENEMAIL_BASE_URL quel que soit le profil actif : les boîtes jetables, les méthodes qui n'ont pas besoin de clé, docs et open.
• —Le http simple est refusé pour toute origine sauf localhost, 127.0.0.1 et ::1, avec le code de sortie 2 : l'API, l'application web, les requêtes de connexion, de jeton et de révocation, et le serveur MCP. Utilisez https pour tout le reste.
• —Un chemin de requête qui sortirait de l'origine de l'API, comme openemail api //example.com/x, s'arrête avec le code de sortie 2 et invalid_path avant tout envoi.

Une connexion par navigateur agit en votre nom, mais certaines choses ne sont jamais approuvées pour une application, quel que soit l'accès choisi :

• —Gérer les clés API. keys:write et keys:manage ne sont jamais accordés, donc créer, faire tourner et révoquer des clés exige une clé API qui détient keys:manage, ou l'application web. openemail me rotate fait tourner la clé avec laquelle vous appelez, il lui faut donc une clé API.
• —La facturation, et les espaces de travail eux-mêmes. Les forfaits, les factures, ainsi que créer, changer ou supprimer un espace de travail restent dans l'application web.
• —Votre adresse gratuite. Une application est approuvée pour un espace de travail professionnel, et l'espace personnel qui contient l'adresse gratuite n'est jamais proposé, selon la même règle que l'API.
• —Les membres et les rôles, sauf si l'approbation couvre tout l'espace de travail. members:write et roles:write sont retirés d'une approbation limitée à certains domaines ou adresses.

Une clé API a sa propre limite. ai compose, ai summarize et chaque commande openemail mcp sauf config passent par le serveur MCP, qui exige une connexion par navigateur, donc avec une clé elles s'arrêtent avec le code de sortie 4 et disent pourquoi.

Avec une connexion par navigateur, quelques changements demandent d'abord un code de vérification, comme dans l'application web. La CLI le demande quand elle en a besoin : elle vous envoie par e-mail un code à six chiffres ou, si la connexion à deux facteurs est activée, demande un code de votre application d'authentification ou l'un de vos codes de secours. Une fois le code correct, la commande s'exécute, et cette connexion n'est plus sollicitée pendant 60 minutes. On ne demande jamais de code à une clé API.

$ openemail webhooks create --url https://acme.com/hooks/openemailWe emailed a code to a•••@acme.com.Verification code: 482913Verified. You will not be asked again for 60 minutes.

• —Tapez r à l'invite pour recevoir l'e-mail à nouveau. Un code erroné indique combien d'essais il reste.
• —Une fois le code accepté, la commande s'exécute une fois de plus, jamais deux.
• —--yes confirme une suppression, mais ne saute jamais un code.
• —Sans surveillance (avec --json ou --no-input, en CI ou sans terminal), personne ne peut taper le code, donc la commande s'arrête avec le code de sortie 4 et ne change rien.
• —Un code permet 5 essais, et après le cinquième code erroné la CLI en propose un nouveau. Chaque connexion peut demander 5 codes par heure et 20 par jour.
• —Dix codes erronés pour une même connexion en 24 heures mettent sa vérification en pause. La CLI indique alors quand elle reprend et s'arrête avec le code de sortie 4 et step_up_paused, sans proposer d'autre code, et l'e-mail qui l'explique nomme l'application.

Lancez openemail verify avant qu'un script ou un client IA ne fasse quelque chose de sensible. Elle demande le code maintenant, et pendant les 60 minutes suivantes chaque commande de ce profil s'exécute sans code, y compris openemail mcp call et le pont MCP local.

openemail verifyopenemail verify --statusopenemail verify --status --jsonopenemail verify --force

• —Le jeton d'accès d'une connexion par navigateur vaut une heure. La CLI le renouvelle avant son expiration et enregistre le nouveau, sans que vous le remarquiez.
• —Chaque jeton de rafraîchissement ne sert qu'une fois. Un ancien jeton utilisé plus de 30 secondes après que la CLI l'a remplacé, par exemple depuis une copie de config.json sur une autre machine, amène le serveur à révoquer entièrement cette connexion : connectez-vous donc sur chaque machine plutôt que de copier le fichier.
• —L'approbation dure autant que vous l'avez choisi sur la page d'approbation. Quand elle prend fin, ou quand l'application est supprimée dans Compte → Applications connectées, la CLI ne peut plus agir pour vous et vous demande de relancer openemail login.
• —openemail logout révoque une connexion par navigateur sur le serveur, ce qui la retire des applications connectées, puis l'oublie sur cet appareil, même quand le serveur est injoignable. --all déconnecte chaque profil.
• —Se déconnecter d'une clé API ne fait que l'oublier ici. La clé continue de fonctionner jusqu'à ce que vous la révoquiez, avec openemail keys revoke <id> ou dans l'application web.

Tout se trouve dans ~/.openemail, ou dans le dossier que nomme OPENEMAIL_CONFIG_DIR. Le dossier n'est lisible que par vous (0700), tout comme chaque fichier qu'il contient (0600). Chaque fichier est écrit dans un fichier temporaire puis renommé à sa place, pour qu'un plantage ne laisse jamais un fichier à moitié écrit, et chaque changement se fait sous un fichier de verrou, pour que des commandes lancées côte à côte ne perdent jamais un profil.