Account API

The account behind the API key: mode, live-mode activation, limits and the next step.

Operation	Endpoint
Retrieve the account	`GET /v1/account`
Update the account	`POST /v1/account`

The Account object

The Checkbox account behind the API key.

Field	Type	Description
`id`	string	Unique identifier of the account (acct_…).
`object`	enum	String representing the object's type. Always "account".
`livemode`	boolean	true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).
`name`	string	Organization name.
`email`	string \| null	Contact email.
`api_version`	string	API version the account is pinned to (default for requests without Checkbox-Version).
`activation`	object	Live-mode activation. Test mode never needs it.
`activation.status`	enum	active: live mode is on; pending: verify a site domain; suspended: contact support. One of `active`, `pending`, `suspended`.
`activation.method`	enum \| null	How the account was activated. One of `domain`, `staff`, `grandfathered`.
`activation.domain`	string \| null	The verified domain that activated it.
`activation.activated_at`	integer \| null	When live mode was activated. Unix timestamp in seconds.
`limits`	object	Fair-use limits (everything is free; these only prevent abuse).
`limits.max_sites`	integer	Fair-use limit of active sites per mode.
`limits.sites`	integer	Active sites in this mode.
`limits.requests_per_minute`	integer	Fair-use API rate limit per mode.
`key`	object	The key that made this request.
`key.type`	enum	Kind of key used for this request. One of `secret`, `restricted`, `publishable`.
`key.role`	enum	Role the key acts with. One of `admin`, `member`, `viewer`.
`key.scopes`	object \| null	Restricted keys: resource permissions.
`key.legacy`	boolean	A legacy sk_live_ organization key.
`publishable_key`	string	Publishable key (pk_…) of this mode for the browser snippet / elements.
`billing`	object	Commercial status.
`billing.plan`	enum	Checkbox is free to use.
`retention`	Retention	Account default retention (sites without their own setting use it).
`legal_hold`	LegalHold	Account-wide legal hold: while active, nothing of this mode's data is deleted.
`created`	integer	When the account was created. Unix timestamp in seconds.
`next_action`	NextAction \| null	What the caller (often an AI agent) should do next.

Retrieve the account

GET /v1/account

Returns the account behind the key: test or live mode, whether live mode is activated, fair-use limits, the publishable key, and next_action. Call this first to check a key.

Scope account:read · Operation retrieveAccount

SDK: checkbox.account.retrieve() (Node) · checkbox.account.retrieve() (Python). MCP / agents: operation retrieveAccount.

Returns

Returns an Account object.

Errors use the standard envelope with a stable code and, where useful, next_action.

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);

const account = await checkbox.account.retrieve();
console.log(account);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

account = checkbox.account.retrieve()
print(account)

Response

{
  "id": "acct_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "account",
  "livemode": false,
  "name": "Acme Subscriptions",
  "email": "ops@acme.example",
  "api_version": "2026-10-30",
  "activation": {
    "status": "pending",
    "method": null,
    "domain": null,
    "activated_at": 1793318400
  },
  "limits": {
    "max_sites": 25,
    "sites": 1,
    "requests_per_minute": 300
  },
  "key": {
    "type": "secret",
    "role": "admin",
    "scopes": null,
    "legacy": false
  },
  "publishable_key": "pk_test_9fT…",
  "billing": {
    "plan": "free"
  },
  "retention": {
    "records_years": 7,
    "superseded_results_days": 30,
    "good_practice_years": 7,
    "problem_history_days": 30
  },
  "legal_hold": {
    "active": false,
    "scope": null,
    "set": null,
    "reason": null
  },
  "created": 1793318400,
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "endpoint": "POST /v1/sites/{site}/domain_verification",
    "url": "https://checkbox.site/docs/concepts/activation#verify"
  }
}

Update the account

POST /v1/account

Pins the account to an API version (requests without a Checkbox-Version header use it; known versions: 2026-10-30), sets the default retention, and turns the account-wide legal hold on or off. Retention and legal hold apply to the key's mode (test mode has its own).

Scope account:write · Idempotent (send Idempotency-Key) · Operation updateAccount

SDK: checkbox.account.update() (Node) · checkbox.account.update() (Python). MCP / agents: operation updateAccount.

Body

Field	Type	Description
`api_version`	string	API version to pin.
`retention`	RetentionParams	Default retention for every site without its own setting. A longer period for superseded check results keeps a fuller timeline of changes to your site.
`retention.records_years`	integer \| null	Years records are kept (1-10). On a site, null returns to the account default.
`retention.superseded_results_days`	integer \| null	Days superseded check results are kept (7-730). On a site, null returns to the account default.
`retention.good_practice_years`	integer \| null	Deprecated: use records_years.
`retention.problem_history_days`	integer \| null	Deprecated: use superseded_results_days.
`legal_hold`	LegalHoldParams	Account-wide legal hold: suspends every deletion of the account's records until turned off.
`legal_hold.active` required	boolean	true turns the hold on, false turns it off.
`legal_hold.reason`	string	Note stored with the hold (who asked, matter).

Returns

Returns an Account object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/account \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "api_version": "2026-10-30"
}'

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const account = await checkbox.account.update({ api_version: '2026-10-30' });
console.log(account);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

account = checkbox.account.update(api_version="2026-10-30")
print(account)

Response

{
  "id": "acct_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "account",
  "livemode": false,
  "name": "Acme Subscriptions",
  "email": "ops@acme.example",
  "api_version": "2026-10-30",
  "activation": {
    "status": "pending",
    "method": null,
    "domain": null,
    "activated_at": 1793318400
  },
  "limits": {
    "max_sites": 25,
    "sites": 1,
    "requests_per_minute": 300
  },
  "key": {
    "type": "secret",
    "role": "admin",
    "scopes": null,
    "legacy": false
  },
  "publishable_key": "pk_test_9fT…",
  "billing": {
    "plan": "free"
  },
  "retention": {
    "records_years": 7,
    "superseded_results_days": 30,
    "good_practice_years": 7,
    "problem_history_days": 30
  },
  "legal_hold": {
    "active": false,
    "scope": null,
    "set": null,
    "reason": null
  },
  "created": 1793318400,
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "endpoint": "POST /v1/sites/{site}/domain_verification",
    "url": "https://checkbox.site/docs/concepts/activation#verify"
  }
}

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.

Account API

#The Account object

#Retrieve the account

#Returns

#Update the account

#Body

#Returns

The Account object

Retrieve the account

Returns

Update the account

Body

Returns