Comment authentifier l'Apidog CLI : Connexion, Jetons et Secrets CI

La première fois que vous exécutez apidog run et qu'il s'arrête avec "No access token found" (aucun jeton d'accès trouvé), vous rencontrez la seule partie du flux de travail en ligne de commande dont personne ne vous prévient. Les drapeaux, les identifiants de scénario, les rapporteurs sont tous faciles à copier depuis un onglet. L'authentification est l'étape où une commande copiée échoue sur votre machine, divulgue un secret dans un journal, ou fonctionne silencieusement sur votre ordinateur portable et échoue en CI pour des raisons que le message d'erreur n'explique pas.

Ce guide est la réponse dédiée à cette étape. Le CLI Apidog est un package npm, apidog-cli, qui exécute les scénarios de test API que vous construisez dans l'application Apidog directement depuis un terminal. Parce que ces scénarios résident dans votre compte, le CLI doit prouver qu'il est autorisé à les récupérer et à les exécuter, et il le fait avec un jeton d'accès. Gérez correctement la gestion du jeton une seule fois et chaque exécution ultérieure sera une ligne de commande simple. Si vous vous trompez, vous combattrez la même erreur d'authentification dans trois environnements différents.

Nous couvrirons tout le sujet : la génération d'un jeton d'accès, la connexion avec apidog login, la vérification de l'utilisateur connecté avec apidog whoami, l'endroit où le jeton est stocké, comment apidog run décide quel jeton utiliser, et la partie que la plupart des équipes ne gèrent pas correctement : la gestion de ce jeton comme un secret en CI au lieu de le coller dans un fichier de pipeline. Les mécanismes d'installation sont décrits dans un guide séparé ; celui-ci ne concerne que l'authentification. Si vous n'avez pas encore installé le CLI, commencez par le guide d'installation d'Apidog CLI, puis revenez ici.

Pourquoi le CLI a besoin d'un jeton d'accès

Le CLI ne contient pas ses propres tests. Il accède à votre projet Apidog, trouve un scénario par son ID et l'exécute de la même manière que l'application de bureau. Cette conception est la raison pour laquelle il a besoin de s'authentifier : le scénario, les valeurs d'environnement, les assertions vivent toutes côté serveur dans votre compte, donc l'exécuteur doit s'identifier avant que le serveur ne les transmette.

Un jeton d'accès est la façon dont il s'identifie. Le jeton est lié à votre compte Apidog, donc une exécution authentifiée avec votre jeton peut faire ce que vous pouvez faire : lire vos projets, récupérer vos scénarios, les exécuter par rapport aux environnements que vous avez définis. C'est aussi pourquoi le jeton est une information d'identification que vous devez protéger. Toute personne le détenant peut exécuter des scénarios en votre nom, contre les environnements ciblés par ces scénarios. Traitez-le comme vous traiteriez un jeton d'accès personnel pour tout autre service.

Il s'agit d'un type d'authentification différent de l'authentification effectuée par vos tests. Vos scénarios envoient probablement leurs propres jetons d'accès (bearer tokens) ou clés API aux points de terminaison testés, et c'est une préoccupation distincte couverte dans les méthodes d'authentification API. Le jeton d'accès du CLI authentifie l'exécuteur auprès d'Apidog. Les identifiants à l'intérieur de vos requêtes authentifient vos requêtes auprès de votre API. Gardez les deux distincts, car ils résident à des endroits différents et sont renouvelés selon des calendriers différents.

Étape 1 : générer un jeton d'accès

Vous créez le jeton dans Apidog, pas depuis le CLI. Il y a deux endroits où il apparaît, et celui que vous utilisez dépend de ce que vous faites.

Pour un jeton lié à votre compte que vous réutiliserez dans plusieurs scénarios, ouvrez l'application Apidog ou la console web, cliquez sur votre avatar et cherchez la section des jetons d'accès API dans les paramètres de votre compte.

Générez-en un, copiez-le immédiatement et stockez-le en lieu sûr, comme un gestionnaire de mots de passe. Vous ne pourrez généralement pas revoir la chaîne complète après avoir quitté la page, ce qui est normal pour les informations d'identification et la raison pour laquelle il faut la copier dès qu'elle apparaît.

Pour un jeton lié à un scénario spécifique que vous intégrez à votre CI, il existe un chemin plus rapide. Ouvrez le scénario de test, accédez à son onglet CI/CD, choisissez l'option de ligne de commande et cliquez pour générer un jeton d'accès. Apidog construit toute la commande apidog run pour vous avec le jeton, l'ID du scénario et l'ID de l'environnement déjà remplis. Cette commande générée est le point de départ canonique, et la copier signifie que vous ne tapez jamais un ID à la main. Le guide complet d'Apidog CLI décrit cet onglet CI/CD en détail.

Dans les deux cas, le résultat est le même : une chaîne de jeton. Ce que vous en faites ensuite est le choix entre deux styles d'authentification.

Étape 2 : choisir votre style d'authentification

Le CLI prend en charge deux façons de présenter le jeton, et elles conviennent à différentes situations.

La première est une connexion stockée. Vous exécutez apidog login une seule fois, le CLI enregistre le jeton sur votre machine, et chaque apidog run ultérieur le lit automatiquement. Aucun jeton sur la ligne de commande après cela. C'est ce que vous voulez sur une machine de développement que vous utilisez tous les jours.

La seconde est par commande. Vous passez --access-token sur l'appel apidog run lui-même, généralement à partir d'une variable d'environnement. Rien n'est stocké, le jeton est fourni frais à chaque fois, et il ne laisse aucune trace sur le disque. C'est ce que vous voulez en CI, où l'exécuteur est éphémère et le jeton provient d'un secret.

Vous utiliserez probablement les deux : la connexion stockée localement et la commande par commande dans le pipeline. Les deux sections suivantes couvrent chacun de ces aspects.

Sur votre propre machine, connectez-vous une seule fois et oubliez le jeton. Le formulaire interactif vous le demande afin que la chaîne n'apparaisse jamais dans l'historique de votre shell :

apidog login

Le CLI demande votre jeton d'accès, vous le collez, et il appuie sur Entrée. En arrière-plan, il valide le jeton auprès d'Apidog avant de sauvegarder quoi que ce soit ; un jeton invalide ou expiré est rejeté sur-le-champ plutôt que d'échouer plus tard lors de votre première exécution. En cas de succès, il confirme le compte avec lequel il s'est connecté et vous indique où il a stocké l'identifiant.

Si vous préférez passer le jeton directement, par exemple dans un script de configuration, utilisez l'option --with-token :

apidog login --with-token YOUR_ACCESS_TOKEN

Une mise en garde avec cette forme : un jeton sur la ligne de commande atterrit dans l'historique de votre shell et peut être lu à partir de la liste des processus pendant l'exécution de la commande. Préférez l'apidog login interactif pour une utilisation manuelle, et réservez --with-token pour une configuration non interactive où vous lisez la valeur d'une variable que vous contrôlez. Ne mettez jamais un vrai jeton dans un script que vous commettez.

Où va le jeton ? Le CLI l'écrit dans un fichier de configuration sous un répertoire .apidog dans votre dossier personnel. Il s'agit d'un magasin d'informations d'identification local sur votre propre machine, ce qui est précisément l'objectif : le jeton se trouve sur le disque où seul votre compte utilisateur peut le lire, et le CLI le récupère à chaque exécution ultérieure sans que vous n'ayez à le retaper. Si vous êtes sur une machine partagée ou temporaire, ignorez la connexion stockée et utilisez plutôt le jeton par commande, afin que rien ne persiste après votre départ.

Étape 4 : vérifier avec apidog whoami

Après vous être connecté, confirmez que cela a fonctionné avant de vous y fier :

apidog whoami

Ceci affiche le compte sous lequel le CLI est actuellement authentifié. C'est le moyen le plus rapide de savoir « suis-je connecté, et sous quel nom ? » sans exécuter un scénario réel. Utilisez-le chaque fois qu'une exécution échoue avec une erreur d'authentification et que vous n'êtes pas sûr si le problème est le jeton ou quelque chose en aval ; si whoami affiche votre compte, la connexion stockée est correcte et vous pouvez chercher ailleurs.

apidog whoami accepte également --access-token si vous souhaitez vérifier un jeton spécifique plutôt que celui stocké. C'est pratique pour confirmer qu'un jeton de CI est valide avant de lui faire confiance dans un pipeline : collez le jeton dans un apidog whoami --access-token VOTRE_JETON_D_ACCES ponctuel depuis un terminal sécurisé, voyez à quel compte il correspond, puis déplacez-le dans votre magasin de secrets.

Lorsque vous avez terminé sur une machine partagée, ou lorsque vous souhaitez passer à un autre compte, effacez l'identifiant stocké :

apidog logout

Ceci supprime le jeton enregistré du fichier de configuration. La prochaine exécution de apidog run nécessitera une nouvelle connexion ou un drapeau --access-token, ce qui est le comportement souhaité après avoir rendu une machine.

Étape 5 : comment apidog run choisit un jeton

Une fois que vous comprenez l'ordre de vérification de l'exécuteur, l'erreur « Aucun jeton d'accès trouvé » n'est plus mystérieuse. Lorsque vous appelez apidog run, le CLI recherche un jeton dans cet ordre :

Le drapeau --access-token passé en ligne de commande, s'il est présent.
Le jeton stocké sur disque à partir d'un précédent apidog login.

S'il ne trouve ni l'un ni l'autre, il s'arrête et vous demande d'exécuter login d'abord ou de passer --access-token. Cette précédence est utile : un drapeau l'emporte toujours sur la connexion stockée, vous pouvez donc être connecté en tant que vous-même au quotidien et toujours utiliser un jeton différent pour une exécution ponctuelle sans vous déconnecter.

En pratique, cela signifie que vos exécutions locales peuvent être aussi courtes que les ID :

apidog run -t 605067 -e 1629989 -n 1 -r cli

Pas de jeton sur cette ligne, car la connexion stockée le fournit. Le -t nomme le scénario par ID, le -e sélectionne l'environnement, le -n 1 l'exécute une fois, et le -r cli affiche un rapport lisible. Comparez cela à la forme CI, où vous passez le jeton explicitement car rien n'est stocké :

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli

Même commande, même scénario, source d'authentification différente. C'est là toute la distinction entre l'authentification locale et CI, et le reste de ce guide vise à bien gérer la partie CI. Pour la référence complète des drapeaux derrière ces exécutions, le guide complet d'Apidog CLI couvre chaque option.

Étape 6 : gérer le jeton comme un secret en CI

C'est là que les équipes se brûlent. La solution est une seule règle : le jeton vit dans le magasin de secrets de votre système CI, et il atteint la commande en tant que variable d'environnement. Il n'apparaît jamais dans un fichier commité, une définition de pipeline vérifiée dans le dépôt, ou un journal de build.

Ne vous connectez pas dans la CI, et n'écrivez pas le jeton dans un fichier créé par le runner. Utilisez la forme --access-token par commande, alimentée par un secret masqué. Chaque exemple ci-dessous suit la même forme, le secret étant nommé une fois dans la plateforme, référencé comme $APIDOG_ACCESS_TOKEN à l'étape d'exécution.

GitHub Actions

Stockez le jeton sous les paramètres du dépôt (Settings), dans "Secrets and variables", puis exposez-le à l'étape via env :

- name: Run API test scenario
  run: |
    apidog run \
      --access-token "$APIDOG_ACCESS_TOKEN" \
      -t 605067 \
      -e 1629989 \
      -r junit,cli
  env:
    APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

GitHub masque automatiquement le secret dans les journaux, et le passer via env le maintient hors de la ligne de commande visible. L'échec le plus courant ici est un décalage de nom : la clé env, la référence ${{ secrets.X }} et le secret que vous avez créé dans les paramètres doivent tous utiliser le même nom. Le workflow complet, y compris les artefacts de rapport, se trouve dans Apidog CLI dans GitHub Actions.

GitLab CI

Stockez APIDOG_ACCESS_TOKEN en tant que variable CI/CD masquée et protégée sous "Settings", jamais dans le fichier .gitlab-ci.yml. Référencez-la ensuite directement, car GitLab injecte les variables de projet dans l'environnement du job :

api-tests:
  stage: test
  image: node:20
  script:
    - npm install -g apidog-cli
    - apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli

Marquer la variable "masquée" indique à GitLab de la masquer dans les journaux des tâches ; la marquer "protégée" la maintient hors des branches non protégées, de sorte qu'un fork ou une branche de fonctionnalité ne puisse pas l'exfiltrer.

Jenkins

Stockez le jeton en tant qu'identifiant Jenkins, puis liez-le dans le bloc environment afin qu'il soit disponible en tant que variable sans jamais être imprimé :

pipeline {
  agent any
  environment {
    APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
  }
  stages {
    stage('API tests') {
      steps {
        sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit,cli'
      }
    }
  }
}

Jenkins masque les informations d'identification liées de cette manière dans la sortie de la console. Si vous construisez le pipeline complet autour de cette étape, Apidog CLI dans un pipeline CI/CD couvre la structure environnante.

Le modèle est identique pour chaque exécuteur : un secret masqué dans la plateforme, une variable d'environnement dans la commande, et le drapeau --access-token qui en lit la valeur. C'est la même discipline que vous appliqueriez à toute information d'identification dans un pipeline, et il est utile de lire les meilleures pratiques de gestion des clés API si vous en gérez plus d'une.

Rotation et révocation des jetons

Les jetons ne sont pas éternels. Faites-les tourner selon un calendrier et révoquez-les dès qu'il est possible qu'un jeton ait été divulgué.

Pour faire tourner un jeton, générez un nouveau jeton dans Apidog, mettez à jour le secret dans chaque système CI qui l'utilise, et exécutez un pipeline pour confirmer que le nouveau jeton fonctionne. Ensuite, révoquez l'ancien jeton depuis le même endroit où vous l'avez créé. Localement, exécutez apidog logout suivi de apidog login avec le nouveau jeton. L'ordre est important : mettez à jour la CI avant de révoquer, ou vous échouerez une construction entre les deux étapes.

Révoquez immédiatement si un jeton apparaît là où il ne devrait pas : un journal, une capture d'écran, un commit, un terminal partagé. La révocation invalide le jeton partout à la fois, donc tout pipeline utilisant encore l'ancienne valeur échouera bruyamment, ce qui est le signal que vous voulez. Une construction échouée est récupérable ; une information d'identification en direct dans un journal public ne l'est pas. Pour l'habitude plus large, les meilleures pratiques de rotation des clés API couvrent la cadence.

Un piège subtil : la régénération d'un jeton dans Apidog invalide le précédent. Si vous régénérez et oubliez de mettre à jour un secret CI, ce pipeline commencera à échouer avec une erreur d'authentification même si rien n'a changé dans le YAML. Lorsqu'une build qui fonctionnait auparavant ne peut plus s'authentifier et que vous n'avez pas touché au fichier de workflow, un jeton régénéré est la première chose à vérifier.

Quand l'authentification échoue

Les erreurs d'authentification se regroupent en quelques causes. Voici comment les distinguer.

« No access token found. » (Aucun jeton d'accès trouvé.) Le CLI n'a trouvé ni le drapeau --access-token ni une connexion stockée. Localement, exécutez apidog login. En CI, confirmez que le secret est renseigné et que le drapeau --access-token le lit ; une variable d'environnement vide produit le même message.

« Invalid access token » (Jeton d'accès invalide) ou une erreur d'authentification en cours d'exécution. Le jeton est incorrect, expiré ou révoqué. Exécutez apidog whoami pour vérifier le jeton stocké, ou apidog whoami --access-token VOTRE_JETON pour vérifier un jeton spécifique. Si aucun ne correspond à votre compte, générez un nouveau jeton et reconnectez-vous.

Fonctionne localement, échoue en CI. Le classique décalage. Votre machine a une connexion stockée, donc les exécutions locales réussissent ; le runner CI n'a rien de stocké et dépend entièrement du secret. Confirmez que le nom du secret correspond exactement entre le paramètre de la plateforme et la commande, et que la valeur a été enregistrée sans espace final ni nouvelle ligne, ce qui est facile à introduire lors d'un copier-coller.

« Accès refusé » sur un scénario spécifique. Le jeton est valide mais le compte derrière lui ne peut pas accéder à ce projet. Vérifiez les identifiants du projet et du scénario, et confirmez que le compte du jeton a accès à ce projet. Il s'agit d'un problème d'autorisation, et non d'authentification ; le CLI a prouvé qui il est, le serveur ne permet tout simplement pas à ce compte d'exécuter ce scénario.

Le jeton atteint la commande mais la build le divulgue toujours. Si jamais vous voyez le jeton brut dans un journal, vous l'affichez quelque part, souvent une ligne de débogage qui imprime la commande complète ou l'environnement. Masquez-le : affichez la longueur du jeton pour confirmer qu'il est renseigné, jamais sa valeur. La plupart des plateformes CI masquent automatiquement les secrets connus, mais un echo manuel de la commande entière peut contourner cela.

Où l'authentification s'intègre dans le flux de travail plus large

L'authentification est la petite porte unique qui rend tout en aval possible. Une fois que le CLI peut prouver qui il est, l'exécution d'un scénario Apidog devient une simple commande, localement dans votre boucle d'édition-test, en CI à chaque push, et même à l'intérieur d'un agent de codage IA qui exécute vos tests pour vous. Ce dernier modèle mérite un coup d'œil si vous travaillez avec des agents : comment utiliser les agents IA pour les tests d'API montre comment un CLI connecté permet à un agent d'exécuter vos scénarios et de lire le résultat, et le serveur Apidog MCP connecte vos spécifications directement à ces agents.

Le modèle mental est simple. Connectez-vous une seule fois sur votre machine avec apidog login, vérifiez avec apidog whoami, et laissez le jeton stocké gérer chaque exécution ultérieure. En CI, ignorez la connexion, gardez le jeton dans un secret masqué, et passez-le par commande avec --access-token. Faites tourner les jetons selon un calendrier, révoquez-les en cas de suspicion, et mettez à jour la CI avant de révoquer. C'est toute l'histoire de l'authentification, et une fois gérée, le CLI s'efface en arrière-plan là où un bon test runner doit être.

Vous continuez à créer des scénarios visuellement dans Apidog, et le CLI les exécute partout où aucun humain ne les surveille. Téléchargez Apidog pour configurer votre premier scénario, puis dirigez l'exécuteur vers celui-ci. Pour tout ce que l'exécuteur peut faire une fois authentifié, le guide complet d'Apidog CLI est la référence à garder ouverte.

button