The build pipeline, the viz command-line tool and external models need access to the product without a person signing in. For that, long-lived API keys are issued: they are not tied to a session and live until they are revoked.
An API key is not the same thing as the installation-wide TEST_AGENT_API_KEY. That one covers the whole installation and serves the Chrome extension connection, while API keys are issued one at a time and each has its own scope. The owner manages them.
Creating
A key is issued in the settings — Settings → API tokens. At the moment of creation its value is shown once: store it where you keep secrets. Only a fingerprint remains on the server, so a lost value cannot be recovered — the key has to be revoked and a new one issued.
A key has a name, a creation date, and a last-used mark. Together they show which key is used where, and whether it is time to replace it.
Scopes
A key carries one of two scopes:
- Read-only — the key reads everything and may flag builds for review. It can never write.
- Read and write — adds the right to create records.
One rule covers every scope: no key can approve a baseline. Approval is a human decision, and it stays with the human in the browser. That way an external tool cannot quietly pin a changed page look and pass it off as the norm.
Where they are used
The key travels in requests as a header in place of the installation-wide key:
Authorization: Bearer taj_…Most often it is needed in three places:
- The build pipeline — sends this header to
/api/extinstead ofX-API-Key. - The
viztool — reads the key from theTEST_AGENT_API_KEYenvironment variable and prefers an API key to the installation-wide one. - The MCP server of the visual tools — accepts the same key.
The scripts family of addresses is available to the same keys as the rest of the external access: through it, scripts are read, edited, trial-run, and their run journal viewed. And the general rule stays in force: even a successful answer from a classifier script approves nothing — the decision always belongs to a human.
What exactly is available at those addresses is described in External API Access.
Revoking
A key is revoked instantly: every client using it stops passing authentication at once. The key’s row stays in the list as a trace — you can see the key existed, when it was issued, and when it was revoked.
Next: how to tune the visual checks for your project — in Visual Testing Settings.