> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tester.army/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Create and manage TesterArmy API keys to authenticate CLI, CI, and API requests.

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:

```bash theme={"theme":"vesper"}
curl https://tester.army/api/v1/runs \
  -H "Authorization: Bearer $TESTERARMY_API_KEY"
```

On your own machine, the CLI does not need an API key: `ta auth` signs you in through the browser (see [CLI](/cli)). For CI and other unattended callers, set:

```bash theme={"theme":"vesper"}
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](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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.