Authentication
CLI tokens, security, and authentication methodsEdit
Supercheck uses prefixed tokens to identify the type and scope of access.
Token Types
| Token | Prefix | Purpose | Scope |
|---|---|---|---|
| CLI token (PAT) | sck_live_ | CLI and API access | Project-scoped, inherits the creator's RBAC permissions |
| Trigger key | sck_trigger_ | CI/CD job triggers | Single job |
| Test token | sck_test_ | Reserved test-token format; not created by the dashboard | Project-scoped |
Legacy trigger keys with the job_ prefix are fully supported. Existing integrations keep working.
Sign In
Run login
supercheck loginThe CLI prints a URL and a short code. You approve the request in your browser and choose the project the CLI may access.
Verify
supercheck whoamiShows your API URL, authenticated project and role. Use supercheck --json whoami to also see the organization. Token identity and expiry are shown when your role can view API keys. Read-only users can verify access too.
The key created by browser login is project-scoped, expires after 90 days, and appears under CLI Tokens where you can revoke it. Each project holds up to 20 active (enabled and unexpired) CLI tokens, and every browser login creates a new one, so revoke tokens you no longer use. See supercheck login for flags and agent-friendly usage. Signing in to the dashboard in a browser does not authenticate the CLI.
Resetting your account password revokes all your CLI tokens, so sign in again afterwards. Trigger keys are not affected.
Create a Token Manually
| Method | Steps |
|---|---|
| Dashboard | Organization → CLI Tokens → Create Token, enter a name and optional expiry, copy the token (shown only once) |
| API | POST /api/cli-tokens with {"name": "CI/CD Pipeline"} |
curl -X POST https://app.supercheck.io/api/cli-tokens \
-H "Authorization: Bearer $SUPERCHECK_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "CI/CD Pipeline"}'Tokens can be enabled, disabled or revoked from the dashboard without deleting them. supercheck whoami shows the current context and supercheck logout clears stored credentials.
Trigger Keys
Trigger keys (sck_trigger_*) give limited access for CI/CD: they can only trigger one specific job, and cannot access other API resources or authenticate other commands.
export SUPERCHECK_TRIGGER_KEY="sck_trigger_..."
curl -X POST https://app.supercheck.io/api/jobs/<id>/trigger \
-H "Authorization: Bearer $SUPERCHECK_TRIGGER_KEY"To wait for the result with job trigger --wait, also supply a CLI token with access to read job details and run results in that project. The CLI reads the job before triggering, then polls the accepted run; a trigger key alone cannot wait. Creating a trigger key requires --show-secrets, because its plaintext value is returned once and cannot be fetched again.
Which Credential Do I Need?
| Task | Needs |
|---|---|
job trigger | SUPERCHECK_TRIGGER_KEY |
job trigger --wait | SUPERCHECK_TRIGGER_KEY and SUPERCHECK_TOKEN |
deploy, diff, whoami, other API commands | SUPERCHECK_TOKEN |
test run --offline, job run --local --offline | Nothing; no contact with Supercheck |
Environment Variables
| Variable | Required | Description |
|---|---|---|
SUPERCHECK_TOKEN | Usually | CLI token for most commands and for job trigger --wait |
SUPERCHECK_TRIGGER_KEY | For job trigger | Job-specific trigger key |
SUPERCHECK_URL | No | Base URL (default: https://app.supercheck.io) |
SUPERCHECK_ORG | No | Default organization ID (UUID) |
SUPERCHECK_PROJECT | No | Default project ID (UUID) |
HTTP_PROXY, HTTPS_PROXY | No | Proxy URL for HTTP / HTTPS requests |
NO_PROXY | No | Hosts to bypass the proxy (comma-separated) |
SUPERCHECK_REQUEST_TIMEOUT_MS | No | Timeout for browser-login requests in milliseconds (5000 to 120000, default 30000) |
SUPERCHECK_ORG and SUPERCHECK_PROJECT override the matching fields in supercheck.config.ts for config resolution. The CLI token itself is project-scoped and determines your actual API access.
SUPERCHECK_TOKEN, SUPERCHECK_URL, SUPERCHECK_TRIGGER_KEY, every proxy setting (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY, in either case) and the TLS settings NODE_TLS_REJECT_UNAUTHORIZED, NODE_EXTRA_CA_CERTS, NODE_OPTIONS, SSL_CERT_FILE and SSL_CERT_DIR are not read from a project's .env file. A repository can be committed by anyone, so letting it choose the credential, the server it is sent to, or a proxy or TLS setting would let a hostile repository intercept your token. Export these in your shell, use your CI secret store, or run supercheck login. Other variables in .env (for example SUPERCHECK_ORG and SUPERCHECK_PROJECT) are still loaded.
Security
| Practice | Why |
|---|---|
| Copy a new token immediately | It is shown only once |
| Keep tokens in your CI secret manager or environment variables, never in config files | The CLI rejects configs containing token patterns |
| Rotate regularly, use separate tokens per environment, set expiry on temporary ones | Limits exposure |
| Prefer trigger keys when you only need to trigger a job | Least privilege |
Avoid --show-secrets in CI logs, shared terminals and agent transcripts | It reveals sensitive values |
The CLI redacts known credential fields in output by default, including notification provider webhook URLs, Discord and Teams webhook credentials, and provider config headers. Monitor target URLs stay visible, while credential headers such as Authorization and Cookie are masked.
Organization and billing administration, including member management and creating projects, require an interactive browser session. Project-scoped CLI tokens receive 403 for these operations, even when their owner is an organization administrator. Tokens still support scoped organization/project discovery, authentication context and authorized resource operations within their project.