Authentication

Pixel Eagle uses two kinds of credentials: user sessions for the web UI, and project tokens for the API, the CLI, and CI pipelines.

User sessions

Signing in through the web UI (GitHub, Google, or Enterprise Sign-On) creates a browser session. Sessions are what you use to browse projects, review comparisons, and manage settings; they are refreshed automatically while you use the site. Everything below is about project tokens, which are independent from your session.

Project tokens

A project token is a bearer token scoped to a single project. It can create runs, upload screenshots, and trigger comparisons for that project, and nothing else: it cannot read other projects, manage members, or change settings. This makes tokens safe to store as secrets in CI.

Creating a token

Open your project's Settings page and go to the Tokens section. Give the token a description (for example github-actions) so you can tell tokens apart later. The token value is shown once at creation; store it as a secret in your CI system.

Only space owners and maintainers can create, list, and revoke tokens (see roles and permissions).

Using a token

Pass the token as a Bearer token in the Authorization header:

curl https://pixel-eagle.com/runs \
  --json '{"branch": "main"}' \
  --oauth2-bearer $PIXEL_EAGLE_TOKEN

The CLI reads it from the PIXEL_EAGLE_TOKEN environment variable or the --token option:

export PIXEL_EAGLE_TOKEN=your_token_here
pixeleagle new-run --metadata '{"branch": "main"}'

# or pass it explicitly
pixeleagle --token your_token_here new-run

Lifetime and revocation

Project tokens do not expire. They stay valid until you revoke them.
Each token tracks when it was last used, shown in the Tokens section of the project settings, so you can spot and remove unused tokens.
Revoking a token from the settings page takes effect immediately: the next request using it is rejected with 401 Unauthorized.

Settings override

By default a token triggers comparisons with the project's configured comparison settings. A token created with allow override may also pass custom settings (evaluator, tolerance, threshold, dilation) when triggering a comparison, without changing the project defaults. Leave it off for tokens that only upload and compare.

Read-only access without accounts: to let someone view results without signing in, use a share link or make the project public. Both grant viewer access only; they can never upload or change anything.