Authentication

Every cloud call, including the REST API, publishing reports, browser rendering, and the hosted MCP server, authenticates with a single bearer token in the Authorization header. There are two kinds of token, and which one you use depends on whether a human or a machine is driving.

curl https://api.squirrelscan.com/v1/credits \
  -H "Authorization: Bearer <token>"

Two token types

Both are sent the same way (Authorization: Bearer <token>); the API tells them apart by prefix.

• API keys are created in the dashboard, debit the org’s credit pool, carry scopes, and get a chosen expiry (default 90 days, or Never). This is the intended public auth mechanism for anything automated.
• CLI login tokens are minted by squirrel auth login, tied to your user, unscoped (full access), and expire. Best for a developer at a terminal.

Environment-aware prefixes

Keys carry an environment segment so a dev key can’t accidentally hit production (and vice-versa): the API rejects cross-environment keys with a clear error.

Scopes

API keys carry per-resource scopes in resource:action form. A key may only call endpoints covered by its scopes; a request outside them returns a clear error naming the missing scope.

Login sessions are unscoped (full access). Scopes only apply to API keys.

Presets

When creating a key, pick a preset instead of hand-picking scopes:

The CI preset is enough for most pipelines. See CI/CD.

Key expiry

Every key is created with an expiry: pick a preset in the create dialog:

An expired key is rejected at the API exactly like a revoked one: the request returns an auth error and, in the CLI, the env token fails closed. The dashboard shows each key’s expiry (or never) and flags expired keys, so rotate before the date to avoid a broken pipeline.

Creating and revoking keys

The fastest path is the terminal: squirrel keys create mints a key without leaving your shell, and squirrel keys list / squirrel keys revoke manage existing ones. Or use the dashboard at app.squirrelscan.com/settings/api-keys:

1. Open Settings → API Keys in your organization.
2. Click Create key, name it (e.g. CI – production), pick a preset or specific scopes, and choose an expiry.
3. The key is shown once: copy and store it securely. It is never displayed again.
4. Revoke a key at any time from the same page; revocation is immediate.

Headless auth with SQUIRRELSCAN_API_KEY

For CI and headless agents, set the SQUIRRELSCAN_API_KEY environment variable to an org API key. No squirrel auth login is required: the CLI reads the token straight from the environment, and the REST API accepts the same value as a bearer token.

SQUIRRELSCAN_API_KEY=sq_xxxxxxxxxxxx squirrel audit https://example.com

It’s authoritative and fails closed

When the CLI needs to authenticate a cloud call it resolves one credential, highest priority first:

1. SQUIRRELSCAN_API_KEY (or its back-compat alias SQUIRREL_API_TOKEN, checked only when the preferred var is unset) is authoritative. It overrides a logged-in session, and is fail-closed: if the token is invalid (revoked, expired, or minted for a different environment) the CLI errors rather than silently falling back to your login session. This keeps CI predictable: the same convention as gh, the Stripe CLI, and AWS.
2. Logged-in session (squirrel auth login), used only when neither env var is set.
3. Unauthenticated: local / deterministic-only audits.

The env token is never written to ~/.squirrel/settings.json. An empty or whitespace-only value is treated as unset (it falls through to the alias, then the login session).

GitHub Actions

- name: Audit
  env:
    SQUIRRELSCAN_API_KEY: ${{ secrets.SQUIRRELSCAN_API_KEY }}
  run: squirrel audit https://example.com --fail-on 'score<90' --yes

Store the key as a repository or organization secret. A CI preset key is enough for most pipelines. See CI/CD for GitLab and generic runners.

Inspecting the active credential

squirrel auth status (alias whoami) prints which credential is active: its source (login session vs env var), and, for API keys, the org and granted scopes. When an env token shadows a logged-in session, it says so.

Related

• squirrel keys: mint, list, and revoke org API keys from the terminal
• CI/CD: gate builds and wire SQUIRRELSCAN_API_KEY into pipelines
• REST API: the surface these tokens authorize
• Hosted MCP server - connect any agent over streamable HTTP with these keys or OAuth
• squirrel auth: the CLI commands that manage login sessions
• Cloud Credits: how authenticated cloud calls are metered