# Account API

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

| Operation | Endpoint |
|---|---|
| [Retrieve the account](#retrieveAccount) | `GET /v1/account` |
| [Update the account](#updateAccount) | `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 {#retrieveAccount}

`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](https://checkbox.site/docs/api/account#the-account-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/account \
  -u "$CHECKBOX_SECRET_KEY:"
```
```node
import Checkbox from '@checkbox-site/cli';

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

const account = await checkbox.account.retrieve();
console.log(account);
```
```python
import os
from checkbox import Checkbox

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

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

```json title="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",
    "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 {#updateAccount}

`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](https://checkbox.site/docs/api/account#the-account-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/account \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "api_version": "2026-10-30"
}'
```
```node
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);
```
```python
import os
from checkbox import Checkbox

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

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

```json title="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",
    "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"
  }
}
```