Skip to content

ACME check-ins & renewals

Four POST requests, all made with the same write-scoped API key (the API Keys page in your dashboard), cover a scheduled ACME renewal run. CertIntel bundles wrappers for simple-acme, Certbot and Posh-ACME - see Download the scripts below. The same flow adapts to any other ACME client.

Call Fires when Status
POST /api/v1/checkins/start Before the scheduled task runs 202
POST /api/v1/checkins After the scheduled task finishes, whether or not anything was due 201
POST /api/v1/renewals/enrich During install/store, with the certificate's real details 201
POST /api/v1/renewals When a renewal actually runs (success or failure) 201

Every request carries one auth header and a JSON body:

X-Api-Key: cik_<prefix>.<secret>
Content-Type: application/json; charset=utf-8

Correlation

Every renewal keeps its own row. Reports that carry a certificate_thumbprint are matched to that certificate's row (reporting key + thumbprint), so each renewal over time is a separate history entry. A notify has no thumbprint, so it is attached to the run's row by renewal_id - the most recent event for that renewal configuration. A thumbprint-less notify/enrich that lands before install creates a pending stub that the later thumbprint report adopts. The renewal_id is never used to merge two different renewals; the dashboard uses it to show a renewal's full history.

Check-in: start signal

A lightweight "I'm about to run" signal. A host that stalls before it can post its completion still leaves a record that it started.

Field Type Notes
task_name string optional label, e.g. simple-acme
computer_name string optional; labels the device

Check-in: completion

Posted after the scheduled task finishes. Backs the Agents page's freshness tracking.

Field Type Notes
status enum started / success / failure / completed / skipped. Use completed for a plain "the run reached its end" bookend that asserts nothing about whether renewals succeeded - pair it with a started check-in so a run that dies partway leaves a started with no completed.
task_name string optional
computer_name string optional
started_at, completed_at string (ISO-8601) optional
message string optional; captured console output
renewals_attempted, renewals_succeeded integer optional, default 0

Renewal event

Posted whenever a renewal actually runs - success or failure.

Field Type Notes
status enum success / failure / pending / superseded
event_type string optional; the ACME client's own verbatim event label, stored as sent (max 60 chars). Client-agnostic and open-ended - simple-acme sends created / success / success-with-errors / failure / cancel / test; another client may send anything else (e.g. renewed, deployed). Independent of status: status is CertIntel's normalised outcome, event_type is the client's raw word. Not validated against any list; an over-length value is a 422.
subject string certificate common name / CN (accepts common_name as an alias)
friendly_name string optional; the client's own label for the certificate (e.g. simple-acme's friendly name) - not the subject/CN. Shown next to the subject, never in place of it.
sans string[] subject alternative names
certificate_thumbprint string SHA-1 thumbprint - the per-certificate correlation key (accepts thumbprint)
old_certificate_thumbprint string blank on first issuance; links the replacement chain (accepts old_thumbprint)
renewal_id string optional; the client's renewal configuration id - stable across renewals. Used only to attach a thumbprint-less notify to its run; never to merge separate renewals. The dashboard groups a renewal's whole history by this id.
cache_file string optional; path the client wrote the issued cert to
store_path string optional; the store / directory the client installed into, e.g. My / WebHosting / an IIS site / a filesystem path
store_type string optional; the store kind, e.g. WinCertStore / PEM / PFX / IIS
certificate_not_before, certificate_expiry, certificate_issued_at string (ISO-8601) optional
acme_client string e.g. simple-acme, certbot, posh-acme
computer_name string optional
errors string optional; client-reported error text (accepts error) - shown as a first-class failure reason
log_output string optional; full run log

Renewal enrich

Posted from the install/store step. Same body shape as the renewal event; the server forces status = pending and creates a stub keyed by certificate_thumbprint that the subsequent renewal event completes. Send at least certificate_thumbprint, subject, sans, certificate_not_before, certificate_expiry and old_certificate_thumbprint.

Download the scripts

Every file below ships with your CertIntel deployment and is mirrored here so it can be fetched without signing in. Each family has a README.md with a full setup and troubleshooting walkthrough. All scripts read CERTINTEL_API_BASE (or CERTINTEL_API_URL / CERTINTEL_CHECKINS_URL) and CERTINTEL_API_KEY from the environment, falling back to values you edit at the top of the file.

simple-acme (verified end-to-end)

Use all three on a host; Checkin-Wrapper.ps1 replaces wacs.exe as the scheduled-task action and exports the config the other two inherit.

Warning

Certbot and Posh-ACME below are example scripts. Review them and test against Let's Encrypt staging before relying on them in production.

Certbot (PowerShell 7 / Linux)

Posh-ACME (Windows PowerShell 5.1+ / PowerShell 7)