Test mode and live mode
Test keys act on an isolated sandbox that never needs activation; live keys monitor your real site once your domain is verified.
Every Checkbox account has two modes, chosen by the key you send — the same model as Stripe.
| Test mode | Live mode | |
|---|---|---|
| Secret key | ck_test_… | ck_live_… (older organization keys sk_live_… also work) |
| Publishable key (browser) | pk_test_… | pk_live_… |
| Data | An isolated sandbox: sites, findings, evidence and events you create with test keys | Your real sites |
| Activation | Never needed | Verify a domain once |
| Scheduled monitoring | Off by default | Daily by default (monitoring_interval_minutes) |
| Preflight checks, plans, setup sessions | Yes | Yes |
| Stripe test subscriptions (test runs) | Yes | Yes (always against Stripe test mode) |
Test keys are free and one click away, so test mode only touches your site: Checkbox scans, monitors, fetches pages and runs test runs for localhost / private addresses (local development) and for hosts within a domain your account has verified (in either mode). Any other host is refused with 403 test_mode_domain_unverified and next_action.type: "verify_domain": no scan (not even one), no scheduled monitoring (held), no server-side page or policy fetch and no test run. The one exception is the setup session's unverified preview of the site's own public homepage and policy pages, which stores nothing. Until the domain is verified you can still preflight pages by sending their rendered HTML (checkPage, verifyTask with html) and test against localhost. Verifying the domain lifts the hold and queues the first scan. Live mode has the same rule: see every website Checkbox visits is verified.
Every object has livemode: true | false, and every response carries the Checkbox-Mode: test | live header. Objects never cross modes: a test key cannot read a live site, and the reverse.
Restricted keys
Restricted keys (rk_test_…, rk_live_…) carry per-resource scopes such as { "checks": "read" } or { "sites": "write" } (write implies read). Give CI jobs and agents the least they need: a key with only checks: read can run every preflight check and nothing else. Each operation's required scope is listed in the API reference and in the OpenAPI document (x-checkbox-scope).
Publishable keys
Publishable keys are safe in browser code. They work only for the browser-facing endpoints of Checkbox Elements (recording a consent, loading a disclosure), and only from pages on your site's domains (the Origin is checked). Every other endpoint refuses them with publishable_key_not_allowed.
Which key do I have?
curl https://app.checkbox.site/v1/account \
-u "$CHECKBOX_SECRET_KEY:"import Checkbox from '@checkbox-site/node';
const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);
console.log(checkbox.mode); // 'test' or 'live', from the key prefix
const account = await checkbox.account.retrieve();
console.log(account.livemode, account.activation.status);import os
from checkbox import Checkbox
checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])
print(checkbox.mode) # "test" or "live", from the key prefix
account = checkbox.account.retrieve()
print(account["livemode"], account["activation"]["status"])Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). You remain solely responsible for your subscription program, and Checkbox takes on no legal liability for it (Terms). Checkbox is a System1 company; Trust center · Status. For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.