Tuto : Obtenir les identifiants OAuth 2.0 pour l'API Gmail

Vous essayez probablement d'exporter des données d'emails ligne par ligne vers un fichier Excel parce que l'export natif de votre CRM a encore planté, n'est-ce pas ?

C'est typique.

On vous demande de faire plus avec moins, et quand vous cherchez une solution pour automatiser ce travail de saisie abrutissant, vous vous heurtez à un mur administratif nommé "Google Cloud Platform".

Ne vous inquiétez pas, c'est fait exprès. En effet, l'interface est conçue par des ingénieurs californiens pour d'autres ingénieurs, et non pour des comptables, des CSM ou des RH qui ont un vrai travail à finir avant 18h.

Pour automatiser vos tâches et arrêter de perdre votre temps sur des copier-coller, la première étape indispensable est d'obtenir les identifiants OAuth 2.0 pour l'API Gmail.

Sans ce sésame, aucun script Python ne pourra accéder à votre boîte de réception et vous resterez bloqué avec vos tâches manuelles et vos regrets.

Ce guide n'est pas là pour faire de la littérature, je suis là pour vous donner les clés du camion le plus vite possible. Je  vais vous guider dans ce processus étape par étape.

Ce sera pénible, mais une fois que vous aurez le fichier credentials.json sur votre disque dur, vous serez tranquille pour un moment.

Allez vous chercher un café, fermez les onglets inutiles, on s'y met.

OAuth 2.0 : Un mal pour un bien.

Avant, on pouvait juste indiquer son mot de passe dans un script et ça fonctionnait, c'était simple, mais c'était une catastrophe au niveau de la sécurité.

Si quelqu'un tombait sur votre script, il avait accès à toute votre vie numérique. Aujourd'hui, Google impose OAuth 2.0, c'est chiant à configurer, je vous l'accorde, mais c'est ce qui protège vos données professionnelles.

Imaginez OAuth comme un badge sécurisé dans un immeuble. Quand vous donnez votre mot de passe à un script, c'est comme donner les clés de votre maison et le code de l'alarme à un inconnu. Avec OAuth, vous créez un badge temporaire qui dit : "Cette personne a le droit d'aller uniquement dans la salle de conférence, et nulle part ailleurs".

Le principe est de créer un "Projet" dans l'univers Google qui va agir comme une fausse application. C'est cette application qui demandera la permission d'accéder à vos mails. Une fois que vous, l'humain, aurez cliqué sur "Accepter", Google générera un token d'accès (jeton) et c'est ce token que votre script utilisera pour travailler à votre place.

Obtenir vos identifiants OAuth 2.0 pour l'API Gmail est la fondation de tout votre système. Sans cela, il ne peut pas y avoir d'authentification.

Ne vous laissez pas intimider par les termes techniques comme "Scopes" ou "Client ID", pour nous, ce sont juste des cases à cocher pour satisfaire la sécurité informatique.

Votre objectif est simple : récupérer un fichier texte nommé credentials.json. Le reste, pour le moment, on s'en fou.

Étape 1 : Créer un projet dans la Google Cloud Console

Tout commence sur la Google Cloud Console disponible ici -> https://console.cloud.google.com/

L'interface est dense, lente et change de couleur tous les six mois.

Connectez-vous avec votre compte Google professionnel (ou votre compte perso si vous faites des tests chez vous) et cherchez le sélecteur de projet.

Il est souvent caché en haut à gauche, dans une liste déroulante à côté du logo Google Cloud.

Si vous n'avez jamais fait ça, la liste sera vide ou contiendra un projet par défaut.

Cliquez sur "Nouveau Projet"

Les pièges de la création de projet

Donnez-lui un nom explicite, évitez "Test" ou "Projet1" car dans six mois, quand vous ferez le ménage, vous risquerez de supprimer "Projet1" par erreur et votre automatisation s'arrêtera net.

Appelez-le par example "Automatisation-Compta" ou "Gmail-Export-Script".

Le système va vous demander d'associer ce projet à une "Organisation".

• Si vous êtes en entreprise (Google Workspace) : Sélectionnez votre domaine, cela permet à l'administrateur réseau de voir ce que vous faites (et de ne pas bloquer votre accès).
• Si vous êtes sur un Gmail gratuit (@gmail.com) : Vous n'aurez pas d'organisation, sélectionnez "Pas d'organisation".

Cliquez sur "Créer" et attendez. Une notification va apparaître en haut à droite.

Attention : une fois le projet créé, Google ne vous y redirige pas toujours, vérifiez bien le nom du projet affiché dans la barre bleue en haut.

Si vous configurez les accès sur le mauvais projet, rien ne fonctionnera.

Activer l'API Gmail spécifiquement

Par défaut, un projet Google Cloud est vide et ne fait rien, cest une mesure de sécurité : on ne donne pas accès aux outils que l'on n'utilise pas.

Il vous faut aller dans la "Bibliothèque d'API" pour lui apprendre à interagir avec Gmail.

1. Ouvrez le menu de navigation (les trois barres en haut à gauche).
2. Allez dans "API et services" > "Bibliothèque".
3. Dans la barre de recherche au centre, tapez "Gmail API".

1. Cliquez sur le résultat "Gmail API".
2. Cliquez sur le bouton bleu "Activer".

Attendez ensuite que le bouton "Activer" devienne "Gérer".

Cela signifie que Google a donné l'autorisation à votre projet d'intéragir avec Gmail.

Félicitation! Vous venez de passer la première étape !

Étape 2 : Configurer l'écran de consentement OAuth

L'écran de consentement est la fenêtre qui s'affiche (pop-up) quand une application demande l'accès à vos données.

Google exige que vous configuriez cet écran même si vous êtes le seul utilisateur de votre propre script.

Allez dans "API et services" > "Écran de consentement OAuth" (OAuth consent screen).

Le choix crucial : Interne ou Externe

On va vous demander de choisir le type d'utilisateur ("User Type").

• Interne (Internal) : Cette option n'est disponible que si vous payez pour Google Workspace. C'est le Graal et cela signifie que seuls les employés de votre entreprise peuvent utiliser le script. Si vous pouvez cocher ça, faites-le, vous n'aurez pas de validation complexe à faire.
• Externe (External) : C'est la seule option pour les comptes @gmail.com gratuits et c'est la plus strict. Votre application sera considérée comme "en test" et vous devrez lister manuellement qui a le droit de s'en servir.

Cliquez sur "Créer".

Remplir les champs obligatoires

Google vous demande beaucoup d'informations, mais seules quelques-unes sont obligatoires :

1. Nom de l'application : Mettez "MonScriptPython".
2. Adresse email assistance utilisateur : Mettez votre email.
3. Coordonnées du développeur : Mettez encore votre email.

Ignorez les champs logo, domaine autorisé, ou liens vers les conditions d'utilisation. Nous ne sommes pas en train de lancer une startup SaaS, nous souhaitons juste créer script.

Cliquez ensuite sur "Créer".

Les Scopes (Portées)

Dans Google Auth Platform, dans le menu à gauche, cliquez sur "Accès aux données", puis sur "Ajouter ou supprimer des niveaux d'accès"

Une liste va s'afficher, recherchez celle qui se termine par https://mail.google.com/ (souvent appelée "Lire, rédiger, envoyer et supprimer définitivement des e-mails dans Gmail").

Pour un script de maintenance ou d'export, ces droits dont nécessaires pour éviter d'être bloqué plus tard. Cochez la case, cliquez sur "Mettre à jour", puis "Sauvegarder".

Ajouter les utilisateurs tests (Vital pour le mode Externe)

Si vous avez choisi "Externe" à l'étape précédente, cette section est la cause de 80% des échecs.

Dans le menu, cliquez sur Audience puis vous verrez une section "Utilisateurs tests" (Test users). L' Etat de votre application est "Test", cela signifie que Google bloque l'accès à tout le monde, sauf aux personnes présentes sur cette liste.

Il est nécessaire de cliquer sur "Add Users" et d'entrer votre propre adresse email (celle avec laquelle vous allez lancer le script).

Si vous oubliez d'effectuer cela, vous obtiendrez une erreur 403 "Access Denied" immédiate.

Ajoutez votre email, validez, terminez.

Étape 3 : Créer les identifiants (Le fichier JSON)

L'écran de consentement est prêt, maintenant nous avons besoin des clés API.

Dans le menu de gauche , cliquez sur "Clients"

Choisir le bon type d'identifiant

Cliquez ensuite sur "Créer un client"

Google vous demande ensuite le "Type d'application", c'est un piège sémantique.

Même si votre script tourne sur un serveur, pour commencer simple et éviter les complications de redirection web, choisissez "Application de bureau" (Desktop App), et donnez-lui un nom comme "Client Python Local".

Cliquez sur "Créer".

Une fenêtre pop-up apparaît avec un "ID Client" et un "Code secret".

Ne les copiez-collez pas, à la place, cliquez sur le bouton "Télécharger au format JSON" (l'icône de téléchargement).

Sauvegardez ce fichier dans votre dossier de travail, puis enommez-le immédiatement en credentials.json.

Si vous le laissez avec son nom par défaut (client_secret_45454...json), vous ferez probablement une faute de frappe dans le script plus tard.

Préparation de l'environnement Python

Avant de lancer le script, il faut préparer votre ordinateur.

Je pars du principe que Python est déjà installé, si ce n'est pas le cas, demandez à votre IT ou installez-le depuis en suivant mon guide d'installation de Python.

Ouvrez votre terminal (ou invite de commande cmd sur Windows) et installez les bibliothèques Google nécessaires. Copiez-collez cette ligne et appuyez sur Entrée :

pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib

Si vous voyez des lignes rouges, il s'agit souvent d'un problème de droits (essayez de lancer le terminal en administrateur) ou de chemin d'accès (PATH). Si c'est vert ou blanc, vous êtes bon ;)

Ces bibliothèques contiennent tout le code complexe pour gérer la cryptographie et les connexions sécurisées.

Script Python 1 : L'authentification initiale

Voici le moment de vérité.

Ce script ne fait qu'une seule chose : il prend votre fichier credentials.json, ouvre une fenêtre pour vous demander votre accord, et fabrique un fichier token.json.

Créez un fichier nommé auth.py dans le même dossier que votre credentials.json et collez-y ce code :

import os.path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow

## C'est ici qu'on définit les droits. Si vous changez ça, il faut supprimer token.json
SCOPES = ['https://www.googleapis.com/auth/gmail.readonly']

def get_credentials():
    creds = None
    # Le fichier token.json stocke les tokens d'accès et de rafraîchissement
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)

    # Si pas de token valide, on se connecte
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            try:
                creds.refresh(Request())
            except Exception as e:
                print(f"Erreur de refresh, on recommence: {e}")
                os.remove('token.json')
                return get_credentials()
        else:
            # C'est ici que le script va chercher votre fichier téléchargé
            flow = InstalledAppFlow.from_client_secrets_file(
                'credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)

        # On sauvegarde le token pour la prochaine fois
        with open('token.json', 'w') as token:
            token.write(creds.to_json())

    return creds

if __name__ == '__main__':
    print("Tentative d'authentification...")
    creds = get_credentials()
    print("Authentification réussie ! Le fichier token.json a été créé.")

Lancez ce script.

Dans le Terminal:

Windows

python auth.py

Mac

python3 auth.py

Votre navigateur va s'ouvrir.

Gérer l'écran "Google n'a pas validé cette application"

C'est le moment où vous allez paniquer, une page d'alerte rouge ou grise va s'afficher : "Google n'a pas validé cette application".

C'est tout à fait normal, rassurez-vous ;)

Google vous protège contre vous-même car votre application n'a pas été auditée par leurs services (ce qui coûte cher et prend des semaines).

1. Cliquez sur "Continuer".
2. Cliquez encore sur "Continuer" pour accéder à votre script non-sécurisé
3. Une page web s'affichera avec écrit: 

   The authentication flow has completed. You may close this window.

Retournez dans votre terminal : il doit afficher "Authentification réussie !" et un fichier token.json est apparu dans le répertoire de votre projet.

Erreurs courantes

Même en suivant le guide, l'informatique reste l'informatique, vous trouverez ci-dessous les erreurs classiques que je traite tous les jours et les raisons techniques derrière.

Erreur 403 : Access Not Configured

Symptôme : Le script plante immédiatement avec un message "Access Not Configured".

Cause : Vous avez sauté une étape, car cette erreur signifie que l'API Gmail n'est pas activée dans la bibliothèque de votre projet Google Cloud.

Solution : Retournez dans la console, cherchez "Gmail API" et cliquez sur le bouton "Activer". Attendez 2 minutes que la propagation se fasse.

Erreur : redirect_uri_mismatch

Symptôme : Une page d'erreur 400 dans le navigateur au moment de la connexion.

Cause Technique : Le protocole OAuth repose sur une URL de rappel (callback). Votre script dit à Google "Renvoie le token sur mon port local X", mais la console Google ne reconnaît pas ce port.

Solution : Dans le script ci-dessus, j'utilise port=0. Cela indique au système d'exploitation de trouver n'importe quel port libre et de gérer la redirection dynamiquement. Si vous avez modifié le script pour mettre un port fixe (ex: 8080), vous devez ajouter http://localhost:8080/ dans les "URI de redirection autorisés" sur la console Google Cloud (section Identifiants).

Restez sur port=0 pour vous simplifier la vie.

Erreur : invalid_grant (Token expiré)

Symptôme : Le script fonctionnait hier, mais aujourd'hui il plante en disant que le token est invalide.

Cause : Si votre application est en mode "Publication : Test" (Étape 2), le token de rafraîchissement expire obligatoirement au bout de 7 jours, c'est une règle stricte de Google pour les applications non vérifiées.

Solution : Supprimez simplement le fichier token.json et relancez le script pour vous reconnecter, c'est pénible, mais c'est le prix de la gratuité.

Erreur : FileNotFoundError: [Errno 2] No such file or directory: 'credentials.json'

Symptôme : Python ne trouve pas votre fichier.

Cause : Vous avez téléchargé le fichier mais vous ne l'avez pas renommé, ou il est dans votre dossier "Téléchargements" au lieu d'être dans le dossier de votre script.

Solution : Déplacez le fichier JSON dans le même dossier que votre script .py et renommez-le strictement credentials.json. Vérifiez également que Windows n'ai pas rajouté une extension masquée (genre credentials.json.json).

Script Python 2 : Le test ultime!

Avoir un token, c'est bien, pourvoir l''utiliser, c'est mieux.

Nous allons vérifier la validité de nos identifiants Oauth pour l'API Gmail et qu'ils sont fonctionnels.

Ce script va donc se connecter à votre compte et récupérer les 5 derniers emails reçus:

Créez un fichier test_gmail.py dans le même dossier où sont présents token.json et credentials.json puis collez ceci :

import os.path
from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build

# Définition des droits d'accès (scopes). 
# Doit être strictement identique à ceux définis dans auth.py.
SCOPES = ['https://www.googleapis.com/auth/gmail.readonly']

def main():
    creds = None
    # Chargement du fichier token.json s'il existe à la racine
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)

    # Vérification de la validité des identifiants
    if not creds or not creds.valid:
        # Cas : Le token est expiré mais contient un jeton de rafraîchissement (Refresh Token)
        if creds and creds.expired and creds.refresh_token:
            print("Token expiré. Actualisation automatique en cours...")
            try:
                # Envoi de la requête de renouvellement à Google
                creds.refresh(Request())
                
                # Enregistrement du nouveau token dans le fichier JSON
                with open('token.json', 'w') as token:
                    token.write(creds.to_json())
                print("Token actualisé avec succès.")
                
            except Exception as e:
                print(f"Erreur lors de l'actualisation du token : {e}")
                print("Suppression du fichier token.json requise. Relancer auth.py.")
                return
        else:
            # Cas : Aucun token valide ou fichier inexistant
            print("Aucun token valide détecté. Exécution de auth.py requise.")
            return

    try:
        # Construction de l'objet de service pour l'API Gmail
        service = build('gmail', 'v1', credentials=creds)

        # Appel API : Récupération de la liste des 5 derniers messages
        # userId='me' indique le compte authentifié
        results = service.users().messages().list(userId='me', maxResults=5).execute()
        messages = results.get('messages', [])

        if not messages:
            print('Aucun message trouvé.')
            return

        print('Aperçu des 5 derniers emails :')
        # Itération sur la liste des messages pour récupérer le contenu (snippet)
        for message in messages:
            # Appel API supplémentaire pour obtenir les détails du message via son ID
            msg = service.users().messages().get(userId='me', id=message['id']).execute()
            print(f"- {msg['snippet'][:100]}...")

    except Exception as error:
        print(f'Une erreur technique est survenue : {error}')

if __name__ == '__main__':
    main()

Si ce script affiche des bouts de phrases qui correspondent à vos derniers emails, félicitations. Vous avez franchi la barrière technique la plus haute.

Maintenance et renouvellement automatique

Une question revient souvent : "Est-ce que je vais devoir cliquer sur 'Autoriser' tous les matins ?".

Non, si c'est correctement configuré.

Le fichier token.json contient deux choses :

1. Access Token : Valide pour environ 1 heure. C'est le badge temporaire.
2. Refresh Token : Valide plus longtemps (ou 7 jours en mode test).

La bibliothèque Google (google-auth) gère cela toute seule, quand le script s'exécute, elle regarde si l'Access Token est périmé. Si c'est le cas, elle va utiliser le Refresh Token pour demander un nouvel Access Token à Google en arrière-plan, sans ouvrir de fenêtre.

Cependant, si vous êtes en mode "Test" (compte Gmail gratuit), le Refresh Token lui-même meurt après 7 jours.

Dans ce cas, le renouvellement automatique échouera. Le script auth.py fourni plus haut gère ce problème : il détectera l'erreur, supprimera le vieux token et ouvrira le navigateur pour vous demander de vous reconnecter, et ainsi générer un nouveau Token.

C'est une contrainte connue et si vous souhaitez vraiment l'éviter, il vous faudra faire vérifier votre application par Google, ce qui est un processus lourd et inutil pour un script personnel.

Conclusion : Et maintenant ?

Vous avez survécu à la bureaucratie de Google.

Vous avez réussi à obtenir les identifiants OAuth 2.0 pour l'API Gmail, ce qui est objectivement la partie la plus ingrate de tout projet d'automatisation.

La plupart des gens abandonnent à l'étape de l'écran de consentement parce qu'ils ont peur de faire bugger quelque chose.

Maintenant que vous avez vos fichiers credentials.json et token.json, gardez-les précieusement et ne les envoyez jamais par email à un collègue "pour qu'il teste".

Si votre collègue a besoin d'automatisation, il doit générer ses propres identifiants (vous pouvez lui partager cet article).

Ne les partagez pas sur un GitHub public, sinon des bots scanneront votre code en quelques secondes pour utiliser votre compte à des fins de spam (et Google fermera votre compte).

À partir de là, les possibilités sont immenses. D'ailleurs, je vous invite à utiliser les scripts de mon article 5 scripts Python pour nettoyer Gmail.

Vous pouvez modifier le script pour télécharger automatiquement les pièces jointes des factures, pour archiver les notifications inutiles, ou pour extraire des données de commandes directement vers un fichier CSV.

Vous venez d'accomplir l'étape la plus complexe, le reste, c'est juste de la logique et un peu de Python. Profitez du temps que vous allez gagner pour rentrer chez vous à une heure décente, pour une fois...