API keys lifecycle

How paid CI keys are created, shown once, rotated or revoked, and what still works when a key expires.

On this page

One-time key reveal

After checkout on Pricing, you are redirected to Developers → API keys where the full secret is shown exactly once. Copy it before dismissing the banner or refreshing the page—it cannot be retrieved again.

GitHub Actions — Store the key in repository secret SIGNALDIFF_CI_API_KEY and your deployment origin in SIGNALDIFF_API_BASE_URL (no /api suffix).
Other CI — Pass the same value in the x-ci-api-key header on POST /api/trigger/ci.
Scripts and integrations — Use the same key for the Agent API (GET /agent/runs, POST /agent/scans, and related routes).
CLI — Same key in SIGNALDIFF_API_KEY; set SIGNALDIFF_API_BASE_URL=https://signaldiff.dev/api (include /api). See the CLI guide. GitHub Actions uses SIGNALDIFF_CI_API_KEY and an origin without /api.
List view — After reveal, only the key prefix (e.g. sck_…) is shown in the table.

Step-by-step workflow wiring is in the CI and GitHub Actions setup guide. The legacy /api-keys URL redirects to Developers → API keys.

Rotate vs revoke

Action	Effect	When to use
Rotate key	Issues a new secret on the same key record; the previous secret stops working immediately. No extra charge. One-time reveal banner shows the new key.	Suspected leak, offboarding a teammate, or periodic rotation policy
Revoke	Permanently disables the key; cannot be restored. No new secret is issued.	You no longer need CI access for this key, or you are replacing it with a new subscription checkout

Rotation requires typing ROTATE in the confirmation prompt on Developers → API keys. Rate limits may apply if you rotate repeatedly in a short window.

After rotation, update every place the old secret was stored—see Security below.

Trial vs paid expiry and 401 behavior

Each key has an Expires date aligned with your Stripe subscription period. During an eligible free trial, the UI also shows Trial ends; the key remains valid for API calls until Expires (or until revoked).

Active key — Not revoked and Expires is in the future. CI triggers, agent enroll, and paid-tier concurrent crawl limits apply.
Expired or revoked key — Requests with that secret return 401 Unauthorized immediately (wrong, missing, expired, or revoked keys are treated the same to callers).
Renewal — If Stripe is still active but the key Expires date is in the past (missed webhook), use Refresh expiry from Stripe on Developers → API keys or Customer agents (POST /api/api-keys/sync-expiry). If the subscription ended, start a new checkout on Pricing to obtain a fresh active key.

Dashboard, history, and schedules keep working. Sign-in with GitHub is separate from the CI API key. When your paid key expires, you drop back to free-plan capabilities: on-demand monitored runs, saved sites, recurring schedules, and run history in the app—only CI/API-triggered automation that depended on the key stops authorizing. Customer agent heartbeat continues (fleet visibility); enroll, rotate, claim, and refresh-credential return 403 with reason: subscription-lapsed until you renew or use Refresh expiry from Stripe (same pages as above). Do not confuse that 403 with agent credential 401 token-expired — see Customer agent expiry recovery.

Concurrent crawl limits (free vs paid)

Signal Diff caps how many crawls your account may have running at once (manual dashboard runs, CI triggers, schedules, and agent-backed jobs all count toward the same tenant limit).

Account state	Max concurrent crawls
Free (no active paid API key)	1
Paid (at least one active API key)	3

If you hit the limit, new starts return 429 Too Many Requests until a run finishes or is cancelled. See also Troubleshooting — rate limits. Plan comparison: Plans and limits and Pricing (checkout).

Billing, cancel, and Stripe portal

Paid API access is billed through Stripe. You can cancel anytime via the Stripe billing portal — use Manage billing on Developers → API keys or Manage subscription on Pricing when signed in with an active paid plan.

Cancel — Your key stays active until the end of the current paid period, then expires with the subscription.
Trial — One 30-day trial per account when eligible; cancel before trial end to avoid charges.
More FAQ answers (free plan, what keys do, expiry): Pricing.

Security: keep CI secrets in sync

Treat API keys like passwords—never commit them to git or paste them in public tickets.
After rotation, update SIGNALDIFF_CI_API_KEY (or your vault equivalent) in every repository and environment that used the old value.
After revoke, remove or disable the old secret in CI so failed pipelines surface quickly.
Agent enrollment tokens are separate one-time credentials; rotating the CI API key does not rotate enrolled agents—re-enroll if needed.

Relationship to customer agent enrollment

Customer agents crawl targets only your network can reach. You need an active paid API key to:

Enroll an agent from the Customer agents page (issues a one-time credential token)
Trigger CI or schedules with execution_mode: agent and a matching agent_pool_id
Call refresh-credential or Rotate after the short-lived agent credential expires

Heartbeat does not require a paid key. When the paid key expires, agents stay visible on Customer agents but stop claiming jobs until you refresh expiry from Stripe or renew.

Install, pools, rotation, expiry recovery, and troubleshooting: Customer agent setup (expiry recovery).