CLI and Coding Agents

API Keys

View as Markdown

Use API keys to authenticate CLI, CI, and programmatic API requests.

Create an API key

  1. Open Profile → API Keys in the TesterArmy dashboard.
  2. Click Create API Key.
  3. Copy the key and store it in your secret manager or CI environment.

API keys are shown once. If you lose a key, revoke it and create a new one.

Bearer token format

Send the key in the Authorization header:

$curl https://tester.army/api/v1/runs \
>  -H "Authorization: Bearer $TESTERARMY_API_KEY"

For the CLI, either run ta auth or set:

$export TESTERARMY_API_KEY="YOUR_KEY"

Agent tokens

An AI agent that cannot use the dashboard can authenticate without an API key by following https://tester.army/auth.md: it registers an identity with WorkOS, you approve it once by signing in and reading back the code shown on the claim page, and it exchanges the result for a short-lived access token. That token is sent in the same Authorization: Bearer header and acts as you, on your team.

Use an API key instead when the caller is CI, the CLI, or a user who belongs to more than one team — an agent token has no way to say which team it means.

Troubleshooting

401 Unauthorized

The API key is missing, malformed, revoked, or belongs to a user who no longer has access to the team.

Check that:

  1. The header is exactly Authorization: Bearer YOUR_KEY.
  2. The key comes from Profile → API Keys.
  3. The key has not been revoked.
  4. The user who created the key still belongs to the team.

Rotate a key

  1. Create a new key.
  2. Update your CLI, CI, or secret manager.
  3. Confirm requests work with the new key.
  4. Revoke the old key.