Certificates API
Signed monitoring certificates with a public verification page and trust badge.
Not insurance.
| Operation | Endpoint |
|---|---|
| List certificates | GET /v1/certificates |
| Retrieve a certificate | GET /v1/certificates/{certificate} |
| Issue a certificate | POST /v1/sites/{site}/certificates |
| Revoke a certificate | 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
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 objects.
Errors use the standard envelope with a stable code and, where useful, next_action.
curl -G https://app.checkbox.site/v1/certificates \
-u "$CHECKBOX_SECRET_KEY:" \
-d limit=3import 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);import os
from checkbox import Checkbox
checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])
certificates = checkbox.certificates.list(limit=3)
print(certificates.data){
"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
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 object.
Errors use the standard envelope with a stable code and, where useful, next_action.
curl https://app.checkbox.site/v1/certificates/cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
-u "$CHECKBOX_SECRET_KEY:"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);import os
from checkbox import Checkbox
checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])
certificate = checkbox.certificates.retrieve("cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(certificate){
"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
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 · 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 object.
In live mode before activation: 403 account_not_activated with next_action.operation_id: "createDomainVerification".
Errors use the standard envelope with a stable code and, where useful, next_action.
curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/certificates \
-u "$CHECKBOX_SECRET_KEY:" \
-H "Content-Type: application/json" \
-d '{}'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);import os
from checkbox import Checkbox
checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])
certificate = checkbox.certificates.create("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(certificate){
"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
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 object.
Errors use the standard envelope with a stable code and, where useful, next_action.
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."
}'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);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){
"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>"
}
}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.