# Agent authentication for Zerocheck

How an agent or a script gets and uses a Zerocheck credential. There is no self-serve signup: access to a Zerocheck instance is provisioned during onboarding on the free tier, and the CLI and MCP server then authenticate against that instance.

## Two credentials

- **Instance access.** The web app on an instance is protected by one shared HTTP Basic password, username `zerocheck`, set by the instance owner. Ask the person who provisioned the instance for it. It is not an API token.
- **Project token.** CLI and MCP calls use 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
npx zerocheck login
```

The CLI prints a URL and a short code. Open the URL, sign in to the instance, enter the code, choose the project, and approve. The code expires after fifteen minutes. The token is saved to `~/.zerocheck/config.json` with owner-only permissions. `npx zerocheck whoami` lists the projects the token can reach; `npx zerocheck logout` revokes it.

## Token for CI or unattended use

Create a project token in Settings and set it as an environment variable. It overrides any saved device token.

```sh
export ZEROCHECK_TOKEN=zc_cli_...
export ZEROCHECK_API=https://app.tryzerocheck.com   # default; set only for a different instance
```

In GitHub Actions the generated workflow reads `ZEROCHECK_TOKEN` from the repository secrets. Fork pull requests do not receive it.

## What the token is used for

Every run, local or hosted, sends the page context needed for AI resolution to the instance's AI service and uploads results and artifacts to the instance. A token is therefore required for local runs too. Test credentials for the app under test are separate: the test refers to them by name (`${NAME}`), and the values live in the shell, the CI secret store, or on the hosted server.

## Do not

- Do not paste tokens or test passwords into YAML tests or into a checklist. Tests that contain a configured secret value are rejected before they run.
- Do not share the instance password with people outside the customer's team; unrelated customers get separate instances.

Related: [CLI quickstart](https://tryzerocheck.com/docs/cli/), [credentials and data handling](https://tryzerocheck.com/docs/security/), [MCP setup](https://tryzerocheck.com/docs/mcp/).

---
Canonical: https://tryzerocheck.com/auth.md
Updated: 2026-09-22