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. |
billing.warranty | enum | The compliance warranty is not offered yet (waitlist only; no coverage). |
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/cli';
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){
"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",
"warranty": "coming_soon"
},
"created": 1793318400,
"next_action": {
"type": "verify_domain",
"message": "Verify your site domain to turn on live mode.",
"operation_id": "createDomainVerification",
"mcp_tool": "call_api",
"url": "https://checkbox.site/docs/api/activation"
}
}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.
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. |
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/cli';
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){
"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",
"warranty": "coming_soon"
},
"created": 1793318400,
"next_action": {
"type": "verify_domain",
"message": "Verify your site domain to turn on live mode.",
"operation_id": "createDomainVerification",
"mcp_tool": "call_api",
"url": "https://checkbox.site/docs/api/activation"
}
}Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.