# Certificates API

> Signed monitoring certificates with a public verification page and trust badge.

Not insurance.

| Operation | Endpoint |
|---|---|
| [List certificates](#listCertificates) | `GET /v1/certificates` |
| [Retrieve a certificate](#retrieveCertificate) | `GET /v1/certificates/{certificate}` |
| [Issue a certificate](#createCertificate) | `POST /v1/sites/{site}/certificates` |
| [Revoke a certificate](#revokeCertificate) | `POST /v1/certificates/{certificate}/revoke` |

## The Certificate object

A signed monitoring certificate: the site met every critical and high obligation for the required streak of days. It is not insurance.

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique identifier of the certificate (cert_…). |
| `object` | enum | String representing the object's type. Always "certificate". |
| `livemode` | boolean | true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox). |
| `site` | string | Certified site. |
| `status` | enum | active while monitoring keeps the site insurable; lapses automatically otherwise. One of `active`, `lapsed`, `revoked`, `superseded`. |
| `domain` | string | Verified domain frozen into the certificate. |
| `issued` | integer | Issue time. Unix timestamp in seconds. |
| `valid_until` | integer | Expiry (renewed automatically while compliant). Unix timestamp in seconds. |
| `renewed` | integer \| null | Last renewal. Unix timestamp in seconds. |
| `ended` | integer \| null | When it lapsed or was revoked. Unix timestamp in seconds. |
| `public_reason` | string \| null | Public reason code shown on the verification page when it ended. |
| `verify_url` | string | Public verification page. |
| `badge` | object | Trust badge for the merchant site. |
| `badge.svg_url` | string | Badge image. |
| `badge.script_url` | string | Badge script. |
| `badge.embed_html` | string | HTML to embed the badge. |

## List certificates {#listCertificates}

`GET /v1/certificates`

Certificates newest first, optionally for one site.

**Scope** `certificates:read` · **Operation** `listCertificates`

SDK: `checkbox.certificates.list()` (Node) · `checkbox.certificates.list()` (Python). MCP / agents: operation `listCertificates`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `limit` | query | integer | Number of objects to return, 1-100 (default 10). |
| `starting_after` | query | string | Cursor: an object id; returns the objects after it (older). |
| `ending_before` | query | string | Cursor: an object id; returns the objects before it (newer). |
| `site` | query | string | Only objects of this site (site_…). |

#### Returns

Returns a list (`{ object: "list", data, has_more, url }`) of [Certificate](https://checkbox.site/docs/api/certificates#the-certificate-object) objects.

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

```curl
curl -G https://app.checkbox.site/v1/certificates \
  -u "$CHECKBOX_SECRET_KEY:" \
  -d limit=3
```
```node
import Checkbox from '@checkbox-site/cli';

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

const certificates = await checkbox.certificates.list({ limit: 3 });
console.log(certificates.data);
```
```python
import os
from checkbox import Checkbox

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

certificates = checkbox.certificates.list(limit=3)
print(certificates.data)
```

```json title="Response"
{
  "object": "list",
  "data": [
    {
      "id": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "certificate",
      "livemode": false,
      "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "status": "active",
      "domain": "acme.example",
      "issued": 1793318400,
      "valid_until": 1793318400,
      "renewed": 1793318400,
      "ended": 1793318400,
      "public_reason": null,
      "verify_url": "https://app.checkbox.site/verify/SC-7Q2K-9M4X",
      "badge": {
        "svg_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.svg",
        "script_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.js",
        "embed_html": "<a href=\"…\"><img src=\"…\" alt=\"…\"></a>"
      }
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}
```

## Retrieve a certificate {#retrieveCertificate}

`GET /v1/certificates/{certificate}`

One certificate with its verification URL and badge embed code.

**Scope** `certificates:read` · **Operation** `retrieveCertificate`

SDK: `checkbox.certificates.retrieve()` (Node) · `checkbox.certificates.retrieve()` (Python). MCP / agents: operation `retrieveCertificate`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `certificate` **required** | path | string | Unique identifier of the certificate (cert_…). |

#### Returns

Returns a [Certificate](https://checkbox.site/docs/api/certificates#the-certificate-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/certificates/cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"
```
```node
import Checkbox from '@checkbox-site/cli';

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

const certificate = await checkbox.certificates.retrieve('cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(certificate);
```
```python
import os
from checkbox import Checkbox

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

certificate = checkbox.certificates.retrieve("cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(certificate)
```

```json title="Response"
{
  "id": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "certificate",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "status": "active",
  "domain": "acme.example",
  "issued": 1793318400,
  "valid_until": 1793318400,
  "renewed": 1793318400,
  "ended": 1793318400,
  "public_reason": null,
  "verify_url": "https://app.checkbox.site/verify/SC-7Q2K-9M4X",
  "badge": {
    "svg_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.svg",
    "script_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.js",
    "embed_html": "<a href=\"…\"><img src=\"…\" alt=\"…\"></a>"
  }
}
```

## Issue a certificate {#createCertificate}

`POST /v1/sites/{site}/certificates`

Issues a signed monitoring certificate once the site has been insurable for the required streak of days with a verified domain and fresh scans. Otherwise fails with resource_conflict and next_action describing what is missing.

**Scope** `certificates:write` · **Idempotent** (send `Idempotency-Key`) · **Live mode needs [activation](https://checkbox.site/docs/concepts/activation)** · **Operation** `createCertificate`

SDK: `checkbox.certificates.create()` (Node) · `checkbox.certificates.create()` (Python). MCP / agents: operation `createCertificate`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `site` **required** | path | string | Unique identifier of the site (site_…). |

#### Returns

Returns a [Certificate](https://checkbox.site/docs/api/certificates#the-certificate-object) object.

In live mode before activation: `403 account_not_activated` with `next_action.operation_id: "createDomainVerification"`.

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/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/certificates \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{}'
```
```node
import Checkbox from '@checkbox-site/cli';

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

const certificate = await checkbox.certificates.create('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(certificate);
```
```python
import os
from checkbox import Checkbox

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

certificate = checkbox.certificates.create("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(certificate)
```

```json title="Response"
{
  "id": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "certificate",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "status": "active",
  "domain": "acme.example",
  "issued": 1793318400,
  "valid_until": 1793318400,
  "renewed": 1793318400,
  "ended": 1793318400,
  "public_reason": null,
  "verify_url": "https://app.checkbox.site/verify/SC-7Q2K-9M4X",
  "badge": {
    "svg_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.svg",
    "script_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.js",
    "embed_html": "<a href=\"…\"><img src=\"…\" alt=\"…\"></a>"
  }
}
```

## Revoke a certificate {#revokeCertificate}

`POST /v1/certificates/{certificate}/revoke`

Revokes an active certificate. The reason stays private; the verification page shows "revoked by merchant".

**Scope** `certificates:write` · **Idempotent** (send `Idempotency-Key`) · **Operation** `revokeCertificate`

SDK: `checkbox.certificates.revoke()` (Node) · `checkbox.certificates.revoke()` (Python). MCP / agents: operation `revokeCertificate`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `certificate` **required** | path | string | Unique identifier of the certificate (cert_…). |

#### Body

| Field | Type | Description |
|---|---|---|
| `reason` **required** | string | Private reason. |

#### Returns

Returns a [Certificate](https://checkbox.site/docs/api/certificates#the-certificate-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/certificates/cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/revoke \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Site rebuilt; re-certify later."
}'
```
```node
import Checkbox from '@checkbox-site/cli';

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

const certificate = await checkbox.certificates.revoke('cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b', { reason: 'Site rebuilt; re-certify later.' });
console.log(certificate);
```
```python
import os
from checkbox import Checkbox

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

certificate = checkbox.certificates.revoke("cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", reason="Site rebuilt; re-certify later.")
print(certificate)
```

```json title="Response"
{
  "id": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "certificate",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "status": "active",
  "domain": "acme.example",
  "issued": 1793318400,
  "valid_until": 1793318400,
  "renewed": 1793318400,
  "ended": 1793318400,
  "public_reason": null,
  "verify_url": "https://app.checkbox.site/verify/SC-7Q2K-9M4X",
  "badge": {
    "svg_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.svg",
    "script_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.js",
    "embed_html": "<a href=\"…\"><img src=\"…\" alt=\"…\"></a>"
  }
}
```