初めて `apidog run` を実行し、「No access token found」（アクセストークンが見つかりません）というメッセージで停止した場合、それはコマンドラインワークフローで誰も教えてくれない部分に遭遇したことになります。フラグ、シナリオID、レポーターはすべてタブから簡単にコピーできます。認証は、コピーしたコマンドがマシンで壊れたり、シークレットがログに漏れたり、またはラップトップでは静かに動作するのに、エラーメッセージが理由を説明しないままCIで失敗するステップです。
このガイドは、そのステップに特化した回答です。Apidog CLIは、Apidogアプリで作成したAPIテストシナリオをターミナルから直接実行するnpmパッケージ `apidog-cli` です。これらのシナリオはあなたのアカウントに存在するため、CLIはそれらを取得して実行する許可があることを証明する必要があり、そのためにアクセストークンを使用します。トークン処理を一度正しく設定すれば、その後の実行はすべてクリーンなワンライナーになります。間違えると、3つの異なる環境で同じ認証エラーに苦しむことになります。
このガイドでは、アクセストークンの生成、`apidog login` を使用したログイン、`apidog whoami` で誰としてログインしているかの確認、トークンの保存場所、`apidog run` がどのトークンを使用するかを決定する方法、そしてほとんどのチームが間違えやすい、パイプラインファイルに貼り付けるのではなくCIでトークンをシークレットとして扱う方法まで、全体を網羅します。インストールに関する詳細は別のガイドにあります。このガイドは認証のみを扱います。まだCLIをインストールしていない場合は、まずApidog CLIインストールガイドから始めて、それからここに戻ってください。
そもそもCLIがトークンを必要とする理由
CLIはそれ自身のテストを保持していません。Apidogプロジェクトにアクセスし、IDでシナリオを見つけ、デスクトップアプリと同じ方法で実行します。この設計が認証を必要とする理由です。シナリオ、環境値、アサーションはすべてあなたのアカウントのサーバー側に存在するため、ランナーはサーバーがそれらを提供する前に自分自身を識別する必要があります。
アクセストークンは、それが自身を識別する方法です。トークンはあなたのApidogアカウントに紐付けられているため、あなたのトークンで認証された実行は、あなたができること、つまりプロジェクトの読み取り、シナリオの取得、定義した環境に対する実行を行うことができます。それが、トークンを保護すべき資格情報である理由でもあります。それを持っている人は誰でも、そのシナリオが対象とする任意の環境に対して、あなたとしてシナリオを実行できます。他のサービスに対するパーソナルアクセストークンを扱うのと同じように扱ってください。
これは、あなたのテストが実行する認証とは異なる種類の認証です。あなたのシナリオは、テスト対象のエンドポイントに独自のベアラートークンやAPIキーを送信するでしょうが、それはAPI認証方法でカバーされている別の懸念事項です。CLIのアクセストークンは、ランナーをApidogに対して認証します。リクエスト内の資格情報は、あなたのAPIに対してリクエストを認証します。これらは異なる場所に存在し、異なるスケジュールでローテーションされるため、混同しないようにしてください。
ステップ1: アクセストークンを生成する
トークンはApidogで作成し、CLIからは作成しません。トークンは2つの場所で表示され、どちらを使用するかはあなたが何をしているかによって異なります。
複数のシナリオで再利用する、あなたのアカウントにスコープされたトークンの場合は、Apidogアプリまたはウェブコンソールを開き、アバターをクリックし、アカウント設定の下にあるAPIアクセストークンセクションを探してください。
トークンを生成したら、すぐにコピーし、パスワードマネージャーなどの安全な場所に保存してください。ページを離れると、通常は完全な文字列を再度見ることができません。これは資格情報としては通常のことであり、表示された瞬間にコピーすべき理由でもあります。
CIに組み込む特定のシナリオに紐付けられたトークンについては、より迅速な方法があります。テストシナリオを開き、CI/CDタブに切り替え、コマンドラインオプションを選択し、アクセストークンを生成するためにクリックします。Apidogは、トークン、シナリオID、環境IDがすでに埋め込まれた完全な `apidog run` コマンドを生成します。その生成されたコマンドは正規の開始点であり、それをコピーすることで手動でIDを入力する必要がなくなります。Apidog CLI完全ガイドでは、そのCI/CDタブについて詳しく説明しています。
いずれの方法でも、出力は同じトークン文字列です。次にそれをどうするかは、2つの認証スタイルの中から選択することになります。
ステップ2: 認証スタイルを選択する
CLIはトークンを提示する2つの方法をサポートしており、それぞれ異なる状況に適しています。
1つ目は、保存されたログインです。`apidog login` を一度実行すると、CLIはトークンをマシンに保存し、その後のすべての `apidog run` は自動的にそれを読み込みます。それ以降、どのコマンドラインにもトークンは表示されません。これは、日常的に使用する開発者マシンで望ましい方法です。
2つ目は、コマンドごとの方法です。`apidog run` 呼び出し自体に `--access-token` を渡します（通常は環境変数から）。何も保存されず、トークンは毎回新しく供給され、ディスクに痕跡を残しません。これは、ランナーが一時的であり、トークンがシークレットから供給されるCIで望ましい方法です。
おそらく、ローカルでは保存されたログインを、パイプラインではコマンドごとの方法の両方を使用することになるでしょう。次の2つのセクションでそれぞれについて説明します。
ステップ3: `apidog login` でローカルにログインする
自分のマシンでは、一度ログインしたらトークンのことを忘れてください。対話形式のプロンプトでトークンが要求されるため、文字列がシェル履歴に表示されることはありません。
apidog login
CLIがアクセストークンを尋ね、それを貼り付けてEnterキーを押します。舞台裏では、何も保存する前にトークンをApidogに対して検証します。無効なトークンや期限切れのトークンは、最初の実行で後から失敗するのではなく、その場で拒否されます。成功すると、ログインしたアカウントを確認し、資格情報がどこに保存されたかを伝えます。
例えばセットアップスクリプト内で、トークンを直接渡したい場合は、`--with-token` フラグを使用します。
apidog login --with-token YOUR_ACCESS_TOKEN
この形式には注意点があります。コマンドライン上のトークンはシェル履歴に残り、コマンド実行中にプロセスリストから読み取られる可能性があります。手動で使用する場合は対話型の `apidog login` を好み、制御する変数から値を読み取る非対話型セットアップには `--with-token` を予約してください。コミットするスクリプトに実際のトークンを決して含めないでください。
トークンはどこに行くのでしょうか？CLIはホームフォルダーの `.apidog` ディレクトリ下の設定ファイルにそれを書き込みます。これはあなたのマシン上のローカル資格情報ストアであり、まさにその通りです。トークンはディスク上にあり、あなたのユーザーアカウントだけが読み取ることができ、CLIはそれを再入力することなくその後のすべての実行でそれを取得します。共有マシンや使い捨てマシンを使用している場合は、保存されたログインをスキップして、代わりにコマンドごとのトークンを使用し、離席後に何も残らないようにしてください。
ステップ4: `apidog whoami` で確認する
ログイン後、それに依存する前に動作したことを確認してください。
apidog whoami
これは、CLIが現在認証されているアカウントを表示します。実際のシナリオを実行せずに、「ログインしているのか、誰としてログインしているのか？」という問いに答える最速の方法です。認証エラーで実行が失敗し、問題がトークンにあるのか、それとも下流にあるのか確信が持てない場合は、いつでもこれを使用してください。`whoami` があなたのアカウントを表示すれば、保存されたログインは問題なく、他の場所を探すことができます。
`apidog whoami` は、保存されたトークンではなく特定のトークンを確認したい場合、`--access-token` も受け入れます。これは、CIトークンをパイプラインで信頼する前に有効であることを確認するのに便利です。安全なターミナルから一時的に `apidog whoami --access-token YOUR_ACCESS_TOKEN` にトークンを貼り付け、どのアカウントに解決されるかを確認し、その後それをシークレットストアに移動させます。
共有マシンでの作業が完了したとき、または別のアカウントに切り替えたいときは、保存された資格情報をクリアします。
apidog logout
これにより、設定ファイルから保存されたトークンが削除されます。次回の `apidog run` は、新しいログインまたは `--access-token` フラグを必要とします。これは、マシンを返却した後に望ましい動作です。
ステップ5: `apidog run` がトークンを選択する方法
ランナーがチェックする順序を理解すれば、「No access token found」（アクセストークンが見つかりません）というエラーは謎ではなくなります。`apidog run` を呼び出すと、CLIはこの順序でトークンを探します。
- コマンドで渡された `--access-token` フラグ（存在する場合）。
- 以前の `apidog login` によってディスクに保存されたトークン。
どちらも見つからない場合、CLIは停止し、最初に `login` を実行するか、`--access-token` を渡すように指示します。この優先順位は便利です。フラグは常に保存されたログインよりも優先されるため、日常的には自分としてログインしたままでも、ログアウトせずに一時的な実行のために別のトークンでオーバーライドできます。
実際には、これはローカル実行がIDと同じくらい短くなることを意味します。
apidog run -t 605067 -e 1629989 -n 1 -r cli
この行にはトークンがありません。保存されたログインがそれを供給するからです。`-t` はシナリオをIDで指定し、`-e` は環境を選択し、`-n 1` は一度実行し、`-r cli` は読みやすいレポートを出力します。一方、何も保存されないためトークンを明示的に渡すCI形式と比較してください。
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli
同じコマンド、同じシナリオですが、認証元が異なります。これがローカル認証とCI認証の全体的な違いであり、このガイドの残りの部分ではCI側を正しく設定する方法について説明します。これらの実行の背後にあるすべてのフラグのリファレンスについては、Apidog CLI完全ガイドであらゆるオプションがカバーされています。
ステップ6: CIでトークンをシークレットとして扱う
これはチームが苦労するところです。解決策は1つのルールです。トークンはCIシステムのシークレットストアに保存され、環境変数としてコマンドに渡されます。コミットされたファイル、リポジトリにチェックインされたパイプライン定義、またはビルドログには決して表示されません。
CI内でログインしたり、ランナーが作成するファイルにトークンを書き込んだりしないでください。マスクされたシークレットから供給されるコマンドごとの `--access-token` 形式を使用してください。以下のすべての例は同じ形式に従っており、シークレットはプラットフォームで一度命名され、実行ステップでは `$APIDOG_ACCESS_TOKEN` として参照されます。
GitHub Actions
トークンをリポジトリの「Settings（設定）」の「Secrets and variables（シークレットと変数）」に保存し、`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はログ内のシークレットを自動的にマスクし、`env` を通じて渡すことで、表示されるコマンドラインからそれを除外します。ここで最も一般的な失敗は名前の不一致です。`env` キー、`${{ secrets.X }}` 参照、およびSettingsで作成したシークレットはすべて同じ名前を使用する必要があります。レポート成果物を含む完全なワークフローは、GitHub ActionsでのApidog CLIにあります。
GitLab CI
`APIDOG_ACCESS_TOKEN` を、`.gitlab-ci.yml` ファイルには決して入れずに、Settingsの下のマスクされた保護されたCI/CD変数として保存します。その後、GitLabはプロジェクト変数をジョブ環境に注入するため、直接参照します。
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
変数を「masked（マスク済み）」とマークすると、GitLabはジョブログからそれを匿名化します。「protected（保護済み）」とマークすると、保護されていないブランチでの使用を防ぎ、フォークや機能ブランチがそれを外部に持ち出すことを阻止します。
Jenkins
トークンをJenkinsの資格情報として保存し、`environment` ブロックでバインドして、印刷されることなく変数として利用できるようにします。
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は、このようにバインドされた資格情報をコンソール出力でマスクします。このステップを中心とした完全なパイプラインを構築する場合、CI/CDパイプラインにおけるApidog CLIが周辺構造をカバーしています。
このパターンはすべてのランナーで同じです。プラットフォームのマスクされたシークレット、コマンド内の環境変数、そしてそれから読み取られる `--access-token` フラグです。これはパイプライン内のどの資格情報にも適用されるべき規律であり、複数の資格情報を管理している場合はAPIキー管理のベストプラクティスを読む価値があります。
トークンのローテーションと取り消し
トークンは永遠ではありません。定期的にローテーションし、漏洩の可能性がある場合は直ちに取り消してください。
ローテーションするには、Apidogで新しいトークンを生成し、それを使用するすべてのCIシステムでシークレットを更新し、新しいトークンが機能することを確認するためにパイプラインを実行します。その後、古いトークンを作成したのと同じ場所から取り消します。ローカルでは、`apidog logout` を実行した後、新しいトークンで `apidog login` を実行します。順序が重要です。取り消す前にCIを更新してください。そうしないと、2つのステップの間でビルドが失敗します。
トークンがログ、スクリーンショット、コミット、共有ターミナルなど、あってはならない場所に表示された場合は、直ちに取り消してください。取り消すと、トークンはすべての場所で同時に無効になります。そのため、古い値を使用しているパイプラインは大きなエラーで失敗しますが、これが望ましいシグナルです。失敗したビルドは回復可能ですが、公開ログに残された稼働中の資格情報は回復できません。より広範な習慣については、APIキーローテーションのベストプラクティスが頻度についてカバーしています。
一つの巧妙な落とし穴があります。Apidogでトークンを再生成すると、以前のトークンは無効になります。再生成した後、CIシークレットを更新するのを忘れると、YAMLファイルには何も変更がないにもかかわらず、そのパイプラインは認証エラーで失敗し始めます。以前は成功していたビルドが突然認証できなくなり、ワークフローファイルに手を加えていない場合、再生成されたトークンが最初に確認すべき点です。
認証が失敗した場合
認証エラーはいくつかの原因に集約されます。それらを区別する方法を以下に示します。
「No access token found」（アクセストークンが見つかりません）。CLIは `--access-token` フラグも保存されたログインもどちらも見つけられませんでした。ローカルでは、`apidog login` を実行します。CIでは、シークレットが設定され、`--access-token` フラグがそれから読み取られていることを確認してください。空の環境変数も同じメッセージを生成します。
「Invalid access token」（無効なアクセストークン）または実行途中の認証エラー。トークンが間違っているか、期限切れか、取り消されています。保存されたトークンを確認するには `apidog whoami` を実行するか、特定のトークンを確認するには `apidog whoami --access-token YOUR_TOKEN` を実行します。どちらもあなたのアカウントに解決されない場合は、新しいトークンを生成して再度ログインしてください。
ローカルでは動作するが、CIでは失敗する。典型的な不一致です。あなたのマシンには保存されたログインがあるため、ローカル実行は成功します。CIランナーには何も保存されておらず、シークレットに完全に依存しています。プラットフォーム設定とコマンドの両方でシークレット名が完全に一致していること、そして値が貼り付け時に発生しやすい末尾のスペースや改行なしで保存されていることを確認してください。
特定のシナリオで「Access denied」（アクセス拒否）。トークンは有効ですが、その背後にあるアカウントがそのプロジェクトにアクセスできません。プロジェクトとシナリオIDを確認し、トークンのアカウントがそのプロジェクトへのアクセス権を持っていることを確認してください。これは認証の問題ではなく、認可の問題です。CLIはそれが誰であるかを証明しましたが、サーバーはそのアカウントにそのシナリオの実行を許可しないだけです。
トークンはコマンドに届くが、ビルドで漏洩してしまう。ログで生のトークンを見かけることがある場合、どこかでそれをエコーしています。多くの場合、完全なコマンドや環境を出力するデバッグ行です。それをマスクしてください。トークンの値ではなく、それが設定されていることを確認するためにトークンの長さを出力してください。ほとんどのCIプラットフォームは既知のシークレットを自動的に匿名化しますが、コマンド全体を手動で `echo` すると、それを無効にしてしまう可能性があります。
認証が大規模なワークフローにどのように適合するか
認証は、後続のすべてを可能にする小さな一回限りのゲートです。CLIが自分が誰であるかを証明できるようになれば、Apidogシナリオの実行は、編集とテストのループ内でのローカル実行、プッシュごとのCIでの実行、さらにはテストを実行するAIコーディングエージェント内での実行まで、単一のコマンドで可能になります。AIエージェントと連携している場合は、最後のパターンは一見の価値があります。AIエージェントをAPIテストに使用する方法では、ログイン済みのCLIがエージェントにシナリオを実行させ、結果を読み取らせる方法を示しています。Apidog MCPサーバーは、あなたの仕様書をそれらのエージェントに直接接続します。
メンタルモデルはシンプルです。自分のマシンで `apidog login` を使って一度ログインし、`apidog whoami` で確認したら、保存されたトークンにそれ以降のすべての実行を任せます。CIでは、ログインをスキップし、トークンをマスクされたシークレットに保持し、`--access-token` を使ってコマンドごとに渡します。定期的にローテーションし、疑わしい場合は取り消し、取り消す前にCIを更新します。これが認証の全容であり、これを処理すれば、CLIは優れたテストランナーのあるべき場所、つまりバックグラウンドに溶け込みます。
引き続きApidogでシナリオを視覚的に作成し、人間が監視していない場所であればどこでもCLIがそれらを実行します。Apidogをダウンロードして最初のシナリオを設定し、ランナーをそれに向けます。認証された後にランナーができることのすべてについては、Apidog CLI完全ガイドが参照すべき資料です。