Wenn Sie apidog run zum ersten Mal ausführen und es mit „Kein Zugriffstoken gefunden“ stoppt, stoßen Sie auf den einen Teil des Befehlszeilen-Workflows, vor dem Sie niemand warnt. Die Flags, die Szenario-IDs und die Reporter lassen sich alle einfach aus einem Tab kopieren. Die Authentifizierung ist der Schritt, bei dem ein kopierter Befehl auf Ihrer Maschine fehlschlägt, ein Geheimnis in ein Protokoll gelangt oder auf Ihrem Laptop leise funktioniert und in CI aus Gründen fehlschlägt, die die Fehlermeldung nicht erklärt.
Dieser Leitfaden ist die spezielle Antwort auf diesen Schritt. Die Apidog CLI ist ein npm-Paket, apidog-cli, das die API-Testszenarien, die Sie in der Apidog-App erstellen, direkt von einem Terminal aus ausführt. Da diese Szenarien in Ihrem Konto gespeichert sind, muss die CLI nachweisen, dass sie berechtigt ist, sie abzurufen und auszuführen, und dies geschieht mit einem Zugriffstoken. Wenn Sie die Token-Handhabung einmal richtig einrichten, ist jeder spätere Lauf eine saubere Ein-Zeilen-Anweisung. Wenn Sie es falsch machen, kämpfen Sie in drei verschiedenen Umgebungen mit demselben Authentifizierungsfehler.
Wir decken die gesamte Oberfläche ab: das Generieren eines Zugriffstokens, das Anmelden mit apidog login, das Überprüfen, als wer Sie angemeldet sind mit apidog whoami, wo das Token gespeichert wird, wie apidog run entscheidet, welches Token verwendet werden soll, und den Teil, den die meisten Teams falsch machen: die Behandlung dieses Tokens als Geheimnis in CI, anstatt es in eine Pipeline-Datei einzufügen. Die Installationsmechanismen sind in einem separaten Leitfaden beschrieben; dieser hier behandelt nur die Authentifizierung. Wenn Sie die CLI noch nicht installiert haben, beginnen Sie mit dem Apidog CLI Installationsleitfaden und kommen Sie dann hierher zurück.
Warum die CLI überhaupt ein Token benötigt
Die CLI führt keine eigenen Tests durch. Sie greift in Ihr Apidog-Projekt ein, findet ein Szenario anhand der ID und führt es auf die gleiche Weise aus, wie es die Desktop-App tun würde. Dieses Design ist der Grund, warum sie sich authentifizieren muss: Das Szenario, die Umgebungswerte, die Assertionen leben alle serverseitig in Ihrem Konto, daher muss sich der Runner identifizieren, bevor der Server dies alles übergibt.
Ein Zugriffstoken ist, wie es sich identifiziert. Das Token ist mit Ihrem Apidog-Konto verknüpft, sodass ein mit Ihrem Token authentifizierter Lauf das tun kann, was Sie tun können: Ihre Projekte lesen, Ihre Szenarien abrufen, sie in den von Ihnen definierten Umgebungen ausführen. Deshalb ist das Token auch ein Anmeldeinformation, das Sie schützen müssen. Jeder, der es besitzt, kann Szenarien in Ihrem Namen ausführen, und zwar in den Umgebungen, auf die diese Szenarien abzielen. Behandeln Sie es so, wie Sie ein persönliches Zugriffstoken für jeden anderen Dienst behandeln würden.
Dies ist eine andere Art der Authentifizierung als die, die Ihre Tests durchführen. Ihre Szenarien senden wahrscheinlich ihre eigenen Bearer-Token oder API-Schlüssel an die zu testenden Endpunkte, und das ist ein separates Thema, das in den API-Authentifizierungsmethoden behandelt wird. Das Zugriffstoken der CLI authentifiziert den Runner bei Apidog. Die Anmeldeinformationen in Ihren Anfragen authentifizieren Ihre Anfragen bei Ihrer API. Halten Sie die beiden getrennt, da sie an verschiedenen Orten leben und nach unterschiedlichen Zeitplänen rotieren.
Schritt 1: Ein Zugriffstoken generieren
Sie erstellen das Token in Apidog, nicht über die CLI. Es gibt zwei Stellen, an denen es auftaucht, und welche Sie verwenden, hängt davon ab, was Sie tun.
Für ein auf Ihr Konto bezogenes Token, das Sie szenarienübergreifend wiederverwenden möchten, öffnen Sie die Apidog-App oder die Webkonsole, klicken Sie auf Ihren Avatar und suchen Sie in Ihren Kontoeinstellungen nach dem Abschnitt für API-Zugriffstoken.
Generieren Sie eines, kopieren Sie es sofort und speichern Sie es an einem sicheren Ort, z. B. in einem Passwortmanager. Sie können die vollständige Zeichenfolge normalerweise nicht mehr sehen, nachdem Sie die Seite verlassen haben, was bei Anmeldeinformationen normal ist und der Grund, sie sofort nach dem Erscheinen zu kopieren.
Für ein Token, das an ein bestimmtes Szenario gebunden ist, das Sie in CI integrieren, gibt es einen schnelleren Weg. Öffnen Sie das Testszenario, wechseln Sie zum CI/CD-Tab, wählen Sie die Befehlszeilenoption und klicken Sie, um ein Zugriffstoken zu generieren. Apidog erstellt den gesamten apidog run-Befehl für Sie, wobei das Token, die Szenario-ID und die Umgebungs-ID bereits ausgefüllt sind. Dieser generierte Befehl ist der kanonische Ausgangspunkt, und das Kopieren bedeutet, dass Sie nie eine ID von Hand eingeben müssen. Der vollständige Apidog CLI-Leitfaden erklärt diesen CI/CD-Tab im Detail.
In jedem Fall ist das Ergebnis dasselbe: eine Token-Zeichenfolge. Was Sie als Nächstes damit tun, ist die Wahl zwischen zwei Authentifizierungsstilen.
Schritt 2: Wählen Sie Ihren Authentifizierungsstil
Die CLI unterstützt zwei Möglichkeiten zur Darstellung des Tokens, die für unterschiedliche Situationen geeignet sind.
Die erste ist eine gespeicherte Anmeldung. Sie führen apidog login einmal aus, die CLI speichert das Token auf Ihrem Computer, und jeder spätere apidog run liest es automatisch. Danach ist kein Token mehr in der Befehlszeile erforderlich. Dies ist das, was Sie auf einer Entwicklermaschine wünschen, die Sie jeden Tag verwenden.
Die zweite Methode ist pro Befehl. Sie übergeben --access-token direkt beim Aufruf von apidog run, normalerweise aus einer Umgebungsvariablen. Es wird nichts gespeichert, das Token wird jedes Mal neu bereitgestellt und hinterlässt keine Spuren auf der Festplatte. Dies ist das, was Sie in CI wünschen, wo der Runner temporär ist und das Token aus einem Geheimnis stammt.
Sie werden wahrscheinlich beides verwenden: die gespeicherte Anmeldung lokal und die pro-Befehl-Variante in der Pipeline. Die nächsten beiden Abschnitte behandeln beides.
Schritt 3: Lokale Anmeldung mit apidog login
Melden Sie sich auf Ihrem eigenen Computer einmal an und vergessen Sie das Token. Das interaktive Formular fragt Sie danach, damit die Zeichenfolge niemals in Ihrer Shell-Historie erscheint:
apidog login
Die CLI fragt nach Ihrem Zugriffstoken, Sie fügen es ein und drücken Enter. Im Hintergrund validiert sie das Token gegen Apidog, bevor etwas gespeichert wird; ein ungültiges oder abgelaufenes Token wird sofort abgewiesen, anstatt später bei Ihrem ersten Lauf fehlzuschlagen. Bei Erfolg bestätigt sie das Konto, mit dem sie sich angemeldet hat, und teilt Ihnen mit, wo die Anmeldeinformationen gespeichert wurden.
Wenn Sie das Token lieber direkt übergeben möchten, zum Beispiel in einem Setup-Skript, verwenden Sie das Flag --with-token:
apidog login --with-token YOUR_ACCESS_TOKEN
Eine Vorsichtsmaßnahme bei dieser Form: Ein Token in der Befehlszeile landet in Ihrer Shell-Historie und kann während der Ausführung des Befehls aus der Prozessliste gelesen werden. Bevorzugen Sie das interaktive apidog login für die manuelle Verwendung und reservieren Sie --with-token für die nicht-interaktive Einrichtung, bei der Sie den Wert aus einer von Ihnen kontrollierten Variable lesen. Legen Sie niemals ein echtes Token in ein Skript, das Sie committen.
Wohin geht das Token? Die CLI schreibt es in eine Konfigurationsdatei in einem .apidog-Verzeichnis in Ihrem Home-Ordner. Das ist ein lokaler Anmeldeinformationsspeicher auf Ihrem eigenen Computer, und genau darum geht es: Das Token liegt auf der Festplatte, wo nur Ihr Benutzerkonto es lesen kann, und die CLI greift es bei jedem späteren Lauf auf, ohne dass Sie es jemals neu eingeben müssen. Wenn Sie an einem gemeinsam genutzten oder temporären Computer arbeiten, überspringen Sie die gespeicherte Anmeldung und verwenden Sie stattdessen das Token pro Befehl, damit nichts nach Ihrem Verlassen bestehen bleibt.
Schritt 4: Überprüfung mit apidog whoami
Nach der Anmeldung bestätigen Sie, dass es funktioniert hat, bevor Sie sich darauf verlassen:
apidog whoami
Dies zeigt das Konto an, als das die CLI derzeit authentifiziert ist. Es ist der schnellste Weg, die Frage „Bin ich angemeldet, und als wer?“ zu beantworten, ohne ein echtes Szenario auszuführen. Verwenden Sie es immer, wenn ein Lauf mit einem Authentifizierungsfehler fehlschlägt und Sie sich nicht sicher sind, ob das Problem das Token oder etwas nachgelagertes ist; wenn whoami Ihr Konto anzeigt, ist die gespeicherte Anmeldung in Ordnung und Sie können woanders suchen.
apidog whoami akzeptiert auch --access-token, wenn Sie ein bestimmtes Token überprüfen möchten anstatt das gespeicherte. Das ist praktisch, um die Gültigkeit eines CI-Tokens zu bestätigen, bevor Sie es in einer Pipeline verwenden: Fügen Sie das Token einmalig in apidog whoami --access-token YOUR_ACCESS_TOKEN von einem sicheren Terminal ein, sehen Sie, zu welchem Konto es gehört, und verschieben Sie es dann in Ihren Geheimnisspeicher.
Wenn Sie an einem gemeinsam genutzten Computer fertig sind oder zu einem anderen Konto wechseln möchten, löschen Sie die gespeicherten Anmeldeinformationen:
apidog logout
Dadurch wird das gespeicherte Token aus der Konfigurationsdatei entfernt. Der nächste apidog run erfordert dann eine neue Anmeldung oder ein --access-token-Flag, was das gewünschte Verhalten ist, nachdem Sie einen Computer zurückgegeben haben.
Schritt 5: Wie apidog run ein Token auswählt
Sobald Sie die Reihenfolge verstehen, in der der Runner prüft, hört der Fehler „Kein Zugriffstoken gefunden“ auf, mysteriös zu sein. Wenn Sie apidog run aufrufen, sucht die CLI in dieser Reihenfolge nach einem Token:
- Das
--access-token-Flag, das im Befehl übergeben wurde, falls vorhanden. - Das auf der Festplatte gespeicherte Token aus einem früheren
apidog login.
Wenn keines gefunden wird, stoppt es und fordert Sie auf, zuerst login auszuführen oder --access-token zu übergeben. Diese Priorität ist nützlich: Ein Flag hat immer Vorrang vor der gespeicherten Anmeldung, sodass Sie im Alltag als Sie selbst angemeldet sein können und trotzdem für einen einmaligen Lauf ein anderes Token überschreiben können, ohne sich abzumelden.
In der Praxis bedeutet dies, dass Ihre lokalen Läufe so kurz wie die IDs sein können:
apidog run -t 605067 -e 1629989 -n 1 -r cli
Kein Token in dieser Zeile, da die gespeicherte Anmeldung es liefert. Das -t benennt das Szenario anhand der ID, -e wählt die Umgebung aus, -n 1 führt es einmal aus und -r cli gibt einen lesbaren Bericht aus. Vergleichen Sie dies mit der CI-Form, bei der Sie das Token explizit übergeben, da nichts gespeichert ist:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli
Gleicher Befehl, gleiches Szenario, andere Authentifizierungsquelle. Das ist der ganze Unterschied zwischen lokaler und CI-Authentifizierung, und der Rest dieses Leitfadens befasst sich damit, den CI-Teil richtig zu machen. Für die vollständige Flag-Referenz hinter diesen Ausführungen deckt der vollständige Apidog CLI-Leitfaden jede Option ab.
Schritt 6: Das Token als Geheimnis in CI behandeln
Hier verbrennen sich Teams die Finger. Die Lösung ist eine einzige Regel: Das Token lebt im Geheimnisspeicher Ihres CI-Systems und erreicht den Befehl als Umgebungsvariable. Es erscheint niemals in einer committeten Datei, einer in das Repo eingecheckten Pipeline-Definition oder einem Build-Protokoll.
Melden Sie sich nicht innerhalb von CI an und schreiben Sie das Token nicht in eine Datei, die der Runner erstellt. Verwenden Sie die pro-Befehl-Form --access-token, die aus einem maskierten Geheimnis gespeist wird. Jedes der folgenden Beispiele folgt dem gleichen Muster: Das Geheimnis wird einmal in der Plattform benannt und im Ausführungsschritt als $APIDOG_ACCESS_TOKEN referenziert.
GitHub Actions
Speichern Sie das Token unter den Repository-Einstellungen, in Secrets and variables, und geben Sie es dann dem Schritt über env bekannt:
- name: API-Testszenario ausführen
run: |
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 605067 \
-e 1629989 \
-r junit,cli
env:
APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
GitHub maskiert das Geheimnis in Protokollen automatisch, und die Übergabe über env hält es von der sichtbaren Befehlszeile fern. Der häufigste Fehler hier ist eine Namensabweichung: der env-Schlüssel, die ${{ secrets.X }}-Referenz und das Geheimnis, das Sie in den Einstellungen erstellt haben, müssen alle denselben Namen verwenden. Der vollständige Workflow, einschließlich Berichtsartefakten, befindet sich in Apidog CLI in GitHub Actions.
GitLab CI
Speichern Sie APIDOG_ACCESS_TOKEN als maskierte, geschützte CI/CD-Variable unter den Einstellungen, niemals in der .gitlab-ci.yml-Datei. Referenzieren Sie es dann direkt, da GitLab Projektvariablen in die Job-Umgebung injiziert:
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
Das Markieren der Variablen als „masked“ weist GitLab an, sie aus den Job-Protokollen zu entfernen; das Markieren als „protected“ verhindert, dass sie auf ungeschützten Branches verfügbar ist, sodass ein Fork oder ein Feature-Branch sie nicht exfiltrieren kann.
Jenkins
Speichern Sie das Token als Jenkins-Anmeldeinformation, und binden Sie es dann im environment-Block, damit es als Variable verfügbar ist, ohne jemals ausgegeben zu werden:
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 maskiert auf diese Weise gebundene Anmeldeinformationen in der Konsolenausgabe. Wenn Sie die gesamte Pipeline um diesen Schritt herum aufbauen, deckt Apidog CLI in einer CI/CD-Pipeline die umgebende Struktur ab.
Das Muster ist bei jedem Runner identisch: ein maskiertes Geheimnis in der Plattform, eine Umgebungsvariable im Befehl und das --access-token-Flag, das daraus liest. Das ist dieselbe Disziplin, die Sie auf jede Anmeldeinformation in einer Pipeline anwenden würden, und es lohnt sich, die Best Practices für das API-Schlüsselmanagement zu lesen, wenn Sie mehr als eine verwalten.
Tokens rotieren und widerrufen
Tokens sind nicht für ewig. Rotieren Sie sie nach einem Zeitplan und widerrufen Sie sie in dem Moment, in dem eines möglicherweise kompromittiert wurde.
Zum Rotieren generieren Sie ein neues Token in Apidog, aktualisieren das Geheimnis in jedem CI-System, das es verwendet, und führen eine Pipeline aus, um zu bestätigen, dass das neue funktioniert. Widerrufen Sie dann das alte Token an derselben Stelle, an der Sie es erstellt haben. Lokal führen Sie apidog logout gefolgt von apidog login mit dem neuen Token aus. Die Reihenfolge ist wichtig: Aktualisieren Sie CI, bevor Sie widerrufen, sonst schlägt ein Build zwischen den beiden Schritten fehl.
Widerrufen Sie sofort, wenn ein Token an einer Stelle auftaucht, an der es nicht sein sollte, z. B. in einem Protokoll, einem Screenshot, einem Commit oder einem gemeinsam genutzten Terminal. Das Widerrufen macht das Token überall sofort ungültig, sodass jede Pipeline, die noch den alten Wert verwendet, lautstark fehlschlägt, was das gewünschte Signal ist. Ein fehlgeschlagener Build ist wiederherstellbar; ein Live-Anmeldeinformation in einem öffentlichen Protokoll nicht. Für die breitere Gewohnheit behandeln die Best Practices für die API-Schlüsselrotation die Häufigkeit.
Eine subtile Falle: Das Neugenerieren eines Tokens in Apidog macht das vorherige ungültig. Wenn Sie ein Token neu generieren und vergessen, ein CI-Geheimnis zu aktualisieren, schlägt diese Pipeline mit einem Authentifizierungsfehler fehl, obwohl sich nichts in der YAML-Datei geändert hat. Wenn ein Build, der zuvor erfolgreich war, plötzlich nicht authentifiziert werden kann und Sie die Workflow-Datei nicht geändert haben, ist ein neu generiertes Token das Erste, was Sie überprüfen sollten.
Wenn die Authentifizierung fehlschlägt
Authentifizierungsfehler lassen sich in einige Ursachen gruppieren. So unterscheiden Sie sie.
„Kein Zugriffstoken gefunden.“ Die CLI hat weder ein --access-token-Flag noch eine gespeicherte Anmeldung gefunden. Lokal führen Sie apidog login aus. In CI bestätigen Sie, dass das Geheimnis befüllt ist und das --access-token-Flag daraus liest; eine leere Umgebungsvariable erzeugt dieselbe Meldung.
„Ungültiges Zugriffstoken“ oder ein Authentifizierungsfehler während des Laufs. Das Token ist falsch, abgelaufen oder widerrufen. Führen Sie apidog whoami aus, um das gespeicherte Token zu überprüfen, oder apidog whoami --access-token YOUR_TOKEN, um ein spezifisches zu überprüfen. Wenn keines davon Ihrem Konto zugeordnet werden kann, generieren Sie ein neues Token und melden Sie sich erneut an.
Funktioniert lokal, schlägt in CI fehl. Die klassische Diskrepanz. Ihr Computer hat eine gespeicherte Anmeldung, daher sind lokale Läufe erfolgreich; der CI-Runner hat nichts gespeichert und hängt vollständig vom Geheimnis ab. Bestätigen Sie, dass der Geheimnisname genau mit der Plattform-Einstellung und dem Befehl übereinstimmt und dass der Wert ohne nachgestelltes Leerzeichen oder Zeilenumbruch gespeichert wurde, was beim Einfügen leicht passieren kann.
„Zugriff verweigert“ bei einem spezifischen Szenario. Das Token ist gültig, aber das dahinterstehende Konto kann dieses Projekt nicht erreichen. Überprüfen Sie die Projekt- und Szenario-IDs und bestätigen Sie, dass das Konto des Tokens Zugriff auf dieses Projekt hat. Dies ist ein Autorisierungsproblem, kein Authentifizierungsproblem; die CLI hat bewiesen, wer sie ist, der Server erlaubt diesem Konto lediglich nicht, dieses Szenario auszuführen.
Das Token erreicht den Befehl, aber der Build leakt es trotzdem. Wenn Sie das Rohtoken jemals in einem Protokoll sehen, geben Sie es irgendwo aus, oft eine Debug-Zeile, die den vollständigen Befehl oder die Umgebung ausgibt. Maskieren Sie es: Drucken Sie die Länge des Tokens, um zu bestätigen, dass es befüllt ist, niemals seinen Wert. Die meisten CI-Plattformen redigieren bekannte Geheimnisse automatisch, aber ein manuelles echo des gesamten Befehls kann dies außer Kraft setzen.
Wo sich die Authentifizierung in den größeren Workflow einfügt
Die Authentifizierung ist das kleine, einmalige Tor, das alles Nachfolgende ermöglicht. Sobald die CLI nachweisen kann, wer sie ist, wird das Ausführen eines Apidog-Szenarios zu einem einzigen Befehl, lokal innerhalb Ihrer Bearbeitungs-Test-Schleife, in CI bei jedem Push und sogar innerhalb eines KI-Code-Agenten, der Ihre Tests für Sie ausführt. Dieses letzte Muster ist einen Blick wert, wenn Sie mit Agenten arbeiten: Wie man KI-Agenten für API-Tests einsetzt zeigt, wie eine angemeldete CLI einem Agenten ermöglicht, Ihre Szenarien auszuführen und das Ergebnis zu lesen, und der Apidog MCP-Server verbindet Ihre Spezifikationen direkt mit diesen Agenten.
Das mentale Modell ist einfach. Melden Sie sich einmal auf Ihrem Computer mit apidog login an, verifizieren Sie sich mit apidog whoami und lassen Sie das gespeicherte Token jeden späteren Lauf ausführen. In CI überspringen Sie die Anmeldung, bewahren das Token in einem maskierten Geheimnis auf und übergeben es pro Befehl mit --access-token. Rotieren Sie es nach Zeitplan, widerrufen Sie es bei Verdacht und aktualisieren Sie CI, bevor Sie widerrufen. Das ist die gesamte Authentifizierungsgeschichte, und wenn sie erledigt ist, tritt die CLI in den Hintergrund, wo ein guter Test-Runner hingehört.
Sie erstellen Szenarien weiterhin visuell in Apidog, und die CLI führt sie aus, wo immer kein Mensch zuschaut. Laden Sie Apidog herunter, um Ihr erstes Szenario einzurichten, und weisen Sie den Runner dann darauf hin. Für alles, was der Runner tun kann, sobald er authentifiziert ist, ist der vollständige Apidog CLI-Leitfaden die Referenz, die Sie offen halten sollten.