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

​
Create an API key

  1. Open Settings → API Keys in the TesterArmy dashboard.
  2. Click New key (Add new key if you have none yet), then Create 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:
On your own machine, the CLI does not need an API key: ta auth signs you in through the browser (see CLI). For CI and other unattended callers, set:

​
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. Agent tokens and ta auth sign-ins name you, not a workspace. If you belong to several workspaces, send the one to act on in the x-testerarmy-team header (its ID or slug); GET /api/v1/me lists them. The CLI does this for you. An API key belongs to one workspace and ignores the header. Use an API key instead when the caller is CI or anything else nobody can approve a sign-in for.

​
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 Settings → 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.