DEV Community

Cover image for How to Authenticate the Apidog CLI: Login, Tokens, and CI Secrets
Hassann
Hassann

Posted on • Originally published at apidog.com

How to Authenticate the Apidog CLI: Login, Tokens, and CI Secrets

The first time you run apidog run and get No access token found, the CLI is telling you one thing: it cannot find an Apidog access token. The command flags may be correct, but the runner still needs to authenticate before it can fetch and execute your saved API test scenario.

Try Apidog today

This guide focuses only on authentication for the Apidog CLI. The CLI is distributed as the npm package apidog-cli and runs API test scenarios created in Apidog from your terminal or CI pipeline. Because those scenarios live in your Apidog account, the CLI needs an access token to access them.

If you have not installed the CLI yet, start with the Apidog CLI installation guide, then come back here.

Why the Apidog CLI needs an access token

The CLI does not contain your tests locally. When you run a command like this:

apidog run -t 605067 -e 1629989 -r cli
Enter fullscreen mode Exit fullscreen mode

the CLI must:

  1. Authenticate to Apidog.
  2. Find the scenario by ID.
  3. Load the selected environment.
  4. Execute the scenario.
  5. Return the report.

The access token authenticates the CLI to Apidog. This is separate from the authentication your API requests may use, such as bearer tokens, API keys, or cookies. Those request-level credentials are part of your test scenario. The CLI token is for accessing Apidog itself.

Treat the CLI access token like any other personal access token. Anyone who has it may be able to run scenarios available to that account.

For request-level authentication concepts, see API authentication methods.

Step 1: Generate an Apidog access token

You generate the token inside Apidog, not from the CLI.

Option A: Generate an account-level token

Use this when you want a token you can reuse across multiple scenarios.

  1. Open the Apidog app or web console.
  2. Click your avatar.
  3. Go to your account settings.
  4. Find the API access token section.
  5. Generate a token.
  6. Copy it immediately.
  7. Store it in a password manager or your CI secret store.

You may not be able to view the full token again after leaving the page, which is expected for credentials.

Apidog access token settings

Option B: Generate a token from a scenario CI/CD tab

Use this when wiring a specific scenario into CI.

  1. Open the test scenario in Apidog.
  2. Go to the CI/CD tab.
  3. Choose the command-line option.
  4. Generate an access token.
  5. Copy the generated apidog run command.

Apidog fills in the token, scenario ID, and environment ID for you. This avoids manually copying IDs.

For more CLI usage details, see the complete Apidog CLI guide.

Step 2: Choose the right authentication method

The Apidog CLI supports two practical authentication patterns.

Use case Recommended method
Local development apidog login
CI/CD pipeline --access-token "$APIDOG_ACCESS_TOKEN"

Use stored login locally. Use per-command tokens in CI.

Step 3: Log in locally with apidog login

On your own machine, authenticate once:

apidog login
Enter fullscreen mode Exit fullscreen mode

The CLI prompts for your access token. Paste the token and press Enter.

This avoids putting the token in your shell history.

After validation, the CLI saves the credential locally and uses it for future commands.

Apidog CLI login

You can also pass the token directly:

apidog login --with-token YOUR_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

Use this only when necessary, such as in a controlled setup script. A token passed directly on the command line may appear in shell history or process listings.

Do not commit a real token into a script.

The stored token is written under a .apidog directory in your home folder. On shared, temporary, or untrusted machines, avoid stored login and use a per-command token instead.

Step 4: Verify authentication with apidog whoami

After logging in, verify the active account:

apidog whoami
Enter fullscreen mode Exit fullscreen mode

This prints the account currently authenticated in the CLI.

Use it before debugging a failing scenario. If whoami succeeds, your stored token is valid and the issue is likely elsewhere.

Apidog whoami command

You can also verify a specific token:

apidog whoami --access-token YOUR_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

This is useful before adding a token to a CI secret store.

To remove the stored credential:

apidog logout
Enter fullscreen mode Exit fullscreen mode

After logout, the next apidog run must use either a fresh apidog login or an explicit --access-token.

Step 5: Understand how apidog run chooses a token

When you run:

apidog run ...
Enter fullscreen mode Exit fullscreen mode

the CLI checks for a token in this order:

  1. The --access-token flag.
  2. The token saved by apidog login.

If neither exists, the CLI returns No access token found.

That means local runs can stay short:

apidog run -t 605067 -e 1629989 -n 1 -r cli
Enter fullscreen mode Exit fullscreen mode

In this command:

  • -t 605067 selects the scenario.
  • -e 1629989 selects the environment.
  • -n 1 runs it once.
  • -r cli prints a CLI report.

Because you already logged in locally, no token is needed in the command.

In CI, pass the token explicitly:

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

Same scenario. Same environment. Different token source.

For the full flag reference, see the complete Apidog CLI guide.

Step 6: Store the token as a CI secret

In CI, do not run apidog login.

Instead:

  1. Store the token in your CI platform’s secret manager.
  2. Expose it as an environment variable.
  3. Pass it to apidog run with --access-token.

Do not paste the token into:

  • GitHub Actions workflow files
  • .gitlab-ci.yml
  • Jenkinsfiles
  • build logs
  • shell scripts committed to the repo

Use a secret named something like:

APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

Then reference it in the run command.

GitHub Actions example

Store the token in repository secrets, then pass it through 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 }}
Enter fullscreen mode Exit fullscreen mode

Common mistakes:

  • The secret name in GitHub does not match secrets.APIDOG_ACCESS_TOKEN.
  • The env variable name does not match $APIDOG_ACCESS_TOKEN.
  • The secret value contains an accidental trailing space or newline.

For a complete workflow example, see Apidog CLI in GitHub Actions.

GitLab CI example

Store APIDOG_ACCESS_TOKEN as a masked, protected CI/CD variable in GitLab settings.

Then reference it in .gitlab-ci.yml:

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
Enter fullscreen mode Exit fullscreen mode

Use:

  • Masked to redact the token from logs.
  • Protected to restrict it to protected branches and tags.

Jenkins example

Store the token as a Jenkins credential, then bind it to an environment variable:

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'
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Jenkins masks credentials bound this way in console output.

For more CI/CD structure, see Apidog CLI in a CI/CD pipeline.

The pattern is the same across platforms:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t SCENARIO_ID -e ENVIRONMENT_ID -r junit,cli
Enter fullscreen mode Exit fullscreen mode

For broader credential handling guidance, see API key management best practices.

Rotate and revoke tokens

Tokens should not live forever.

To rotate a token safely:

  1. Generate a new token in Apidog.
  2. Update every CI secret that uses it.
  3. Run the pipeline to confirm the new token works.
  4. Revoke the old token.
  5. On local machines, run: 
apidog logout
apidog login
Enter fullscreen mode Exit fullscreen mode

Then paste the new token.

Update CI before revoking the old token. Otherwise, your next build may fail.

Revoke a token immediately if it appears in:

  • a log
  • a screenshot
  • a commit
  • a shared terminal
  • a pasted command in chat

If a previously working pipeline suddenly fails with an auth error and no YAML changed, check whether the token was regenerated or revoked.

For rotation practices, see API key rotation best practices.

Troubleshooting Apidog CLI authentication

No access token found

The CLI found neither:

  • --access-token
  • a token saved by apidog login

Fix locally:

apidog login
Enter fullscreen mode Exit fullscreen mode

Fix in CI:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r cli
Enter fullscreen mode Exit fullscreen mode

Also confirm the environment variable is not empty.

Invalid access token

The token may be wrong, expired, or revoked.

Check the stored token:

apidog whoami
Enter fullscreen mode Exit fullscreen mode

Check a specific token:

apidog whoami --access-token YOUR_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

If it fails, generate a new token.

Works locally but fails in CI

Your local machine probably has a stored login. The CI runner does not.

Check:

  • The CI secret exists.
  • The secret name matches exactly.
  • The environment variable name matches the command.
  • The token value has no extra spaces or newlines.
  • The pipeline is running on a branch allowed to access the secret.

Access denied for a scenario

The token is valid, but the account does not have access to that project or scenario.

Check:

  • Scenario ID
  • Environment ID
  • Project permissions
  • Account associated with the token

This is an authorization issue, not a token parsing issue.

Token appears in logs

If the raw token appears in logs, remove any command that prints it.

Do not run:

echo "$APIDOG_ACCESS_TOKEN"
Enter fullscreen mode Exit fullscreen mode

If you need to confirm the variable exists, print only its length:

echo "Token length: ${#APIDOG_ACCESS_TOKEN}"
Enter fullscreen mode Exit fullscreen mode

Where authentication fits in the full workflow

Once authentication is configured, the CLI becomes a repeatable test runner:

Local development:

apidog login
apidog whoami
apidog run -t 605067 -e 1629989 -r cli
Enter fullscreen mode Exit fullscreen mode

CI/CD:

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

The mental model is simple:

  • Use apidog login on your own machine.
  • Use apidog whoami to verify the active account.
  • Use --access-token with a masked secret in CI.
  • Rotate tokens on a schedule.
  • Revoke tokens immediately if they leak.

Authentication is also useful when integrating test runs with AI-assisted workflows. For related examples, see how to use AI agents for API testing and the Apidog MCP server.

You can keep authoring scenarios visually in Apidog, then run them from the CLI wherever automation needs them. Download Apidog to create your first scenario, and keep the complete Apidog CLI guide nearby for the full runner reference.

Top comments (0)