# Agent authentication for Zerocheck

How an agent or a script gets and uses a Zerocheck credential. There is no self-serve signup: each customer's instance is provisioned by hand during onboarding, and the CLI then authenticates against that instance. There is no default public service, so `ZEROCHECK_API` must name the instance.

## Two credentials

- **Instance access.** The web app on an instance is protected by one shared instance password, set by the instance owner and entered on the instance's sign-in page. Ask the person who provisioned the instance for it. It is not an API token, and there are no separate user accounts, roles or SSO.
- **Project token.** The CLI uses a per-project token (`zc_cli_...`). It is created in two ways: by approving a device login, or in the web app's Settings, where it can also be revoked.

## Device login for a machine

```sh
export ZEROCHECK_API="https://your-instance.example.com"
npx zerocheck login
```

The CLI prints a URL and a short code. Open the URL, sign in to the instance, confirm the code, choose the project and approve. A person has to do this; an agent cannot complete it. The code expires after fifteen minutes. The token is saved to `~/.zerocheck/config.json` with owner-only permissions and works only with that instance. `npx zerocheck whoami` shows the instance and the project; `npx zerocheck logout` revokes the token and clears it.

## Token for CI or unattended use

Create a project token in Settings and set it as an environment variable, together with the instance. A token without `ZEROCHECK_API` is refused.

```sh
export ZEROCHECK_API="https://your-instance.example.com"
export ZEROCHECK_TOKEN=zc_cli_...
```

In CI, keep both in your CI system's variables and secrets. GitHub Actions does not give repository secrets to pull requests from forks.

## What the token is used for

Your instance makes every decision in a run, so a token is required for every CLI run. The CLI sends the instance the selected tests and what the browser shows; the instance makes the model calls and keeps the results. Test credentials for the app under test are separate: a test refers to them by name (`${NAME}`), and the CLI reads the values from the environment where it runs and sends only their names.

## Do not

- Do not paste tokens or test passwords into YAML tests or into a checklist. A test that writes out a configured secret value is refused before anything is sent.
- Do not share the instance password with people outside the customer's team. Anyone with it can see every project on that instance.

Related: [CLI quickstart](https://tryzerocheck.com/docs/cli/), [credentials and data handling](https://tryzerocheck.com/docs/security/), [using a coding agent](https://tryzerocheck.com/docs/mcp/).

---
Canonical: https://tryzerocheck.com/auth.md
Updated: 2026-11-01