API reference
Complete endpoint catalog, grouped by resource. Each row lists the route, method, minimum role, and a cross-link to the feature page that describes the semantics + request / response bodies. For the auth + conventions, see Overview and Authentication.
In-app API docs
The running application ships an interactive API reference at /api-docs (in the
web UI, under Help) with request/response examples for every endpoint. This page is a
human-readable index of the same surface.
Authentication & user
| Method | Path | Role | See |
|---|---|---|---|
| POST | /auth/login | anonymous | Login |
| POST | /auth/logout | any | Logout |
| POST | /auth/refresh | any | Refresh flow |
| GET | /auth/me | any | Who am I |
| POST | /auth/otp/verify | anonymous (OTP session) | 2FA |
| POST | /auth/totp/setup, /auth/totp/verify-setup | any (self) | 2FA |
| GET | /auth/totp/status | any (self) | 2FA |
| POST | /auth/totp/disable, /auth/totp/recovery-codes | any (self) | 2FA |
Organisation / admin
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST | /users, PUT /users/{id}/roles | owner | Users |
| GET/PUT | /settings/ldap | owner | LDAP |
| GET/PUT | /settings/syslog | admin | Syslog |
| GET/PUT | /settings/general | admin | — |
| GET/PUT | /settings/license | admin | License |
| PUT | /settings/license/api-key | admin | License |
| PUT/DELETE | /settings/license/offline | admin | License |
| POST | /settings/license/validate | admin | License |
| GET | /license/status | any | License status |
| GET | /audit-logs | admin (org scope). The project-scoped /projects/{id}/audit-logs and its /export are readable by any project viewer. | Audit logs |
| GET | /audit-logs/export | admin | Audit export |
| GET/POST/PATCH/DELETE | /organizations (& /organizations/{id}) | GET: any authenticated user · writes: admin | — |
| GET/POST/PATCH/DELETE | /projects (& /projects/{id}) | create and delete: owner · edit: project admin | — |
| GET | /ca-providers | viewer | catalogue of ACME CAs the backend knows by default |
Project — CA providers
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/acme-accounts | read: viewer · writes: admin | ACME accounts |
| POST | /projects/{projectId}/acme-accounts/{id}/validate | admin | re-check CA connection |
| GET | /projects/{projectId}/acme-accounts/{id}/usage | viewer | certs referencing this account |
| GET/POST/PATCH/DELETE | /projects/{projectId}/msca-connections | read: viewer · writes: admin | MSCA |
| POST | /projects/{projectId}/msca-connections/{id}/sync-templates | admin | refresh the template catalogue |
| POST | /projects/{projectId}/msca-connections/{id}/test | admin | probe CES / CEP |
Project — DNS
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/dns-credentials | read: viewer · writes: admin | DNS providers |
| POST | /projects/{projectId}/dns-credentials/{id}/test | admin | smoke-test the credential |
| GET/POST/PATCH/DELETE | /projects/{projectId}/zones | read: viewer · writes: admin | Zones |
| GET | /projects/{projectId}/zones/{id}/rate-limits | viewer | weekly budget + projection |
Project — certificates
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/certificates | viewer (list) / operator (mutate) | Issue |
| POST | /projects/{projectId}/certificates/import | admin | Import |
| POST | /projects/{projectId}/certificates/{id}/reimport | admin | Import |
| POST | /projects/{projectId}/certificates/{id}/renew | operator | Renew |
| POST | /projects/{projectId}/certificates/{id}/reissue | operator | Reissue |
| POST | /projects/{projectId}/certificates/{id}/revoke | admin | Revoke |
| POST | /projects/{projectId}/certificates/{id}/download | operator | Returns the payload directly; optional {"artifact_id"} selects a retained version — Download |
| POST | /projects/{projectId}/certificates/{id}/validate-manual-dns | operator | Manual DNS |
| GET | /projects/{projectId}/certificates/{id}/events | viewer | Timeline |
| GET | /projects/{projectId}/certificates/{id}/jobs | viewer | jobs scoped to this cert |
| GET | /projects/{projectId}/certificates/{id}/dependencies | viewer | Dependencies |
| GET | /projects/{projectId}/certificates/{id}/risk | viewer | Risk |
| GET/PUT/DELETE | /projects/{projectId}/certificate-policy | operator | Policy |
Project — distribution
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/modules | operator | Modules |
| POST | /projects/{projectId}/modules/{id}/health | admin | live health check |
| POST | /projects/{projectId}/module-browse/{moduleType}/{kind} | operator with a saved target_id; admin for an inline spec or a credential_id other than the target's own | live pickers (IIS sites / bindings / app-pools / placement-preview, Kubernetes namespaces / secrets / workloads, Vault mounts / secrets, Azure Key Vault certificates, Exchange servers, MerlinCDN distributions / canonical-names); read-only, 60/min per project, 500 rows max (IIS, Kubernetes, Vault, Azure Key Vault, Exchange) |
| GET/POST/PATCH/DELETE | /projects/{projectId}/credentials | read: viewer · writes: admin (they hold secrets) | Module creds |
| POST | /projects/{projectId}/credentials/{id}/test | admin | resolve the credential; reports its shape, never its value |
| GET | /projects/{projectId}/secret-stores · /{id} · /types | viewer | External secret stores |
| POST/PATCH/DELETE | /projects/{projectId}/secret-stores[/{id}] | admin | a store holds the connection to your secret manager |
| POST | /projects/{projectId}/secret-stores/{id}/test | admin | live connectivity + auth check |
| GET/POST/PATCH/DELETE | /projects/{projectId}/targets | operator | Targets |
| GET/POST/PATCH/DELETE | /projects/{projectId}/target-groups | operator | Target groups |
| GET/POST/PATCH/DELETE | /projects/{projectId}/path-sets | operator | Path sets |
| GET/POST/PATCH/DELETE | /projects/{projectId}/action-sets | operator | Action sets |
| POST | /projects/{projectId}/action-sets/lint | operator | template-variable lint |
| GET/POST/PATCH/DELETE | /projects/{projectId}/variables | operator | Variables |
| GET/POST/PATCH/DELETE | /projects/{projectId}/certificates/{id}/distributions | operator | attach / edit. The list response omits last_target_results (up to 200 per-target subdocs per row) |
| GET | .../distributions/{id} | viewer | one distribution with its full last_target_results history |
| POST | .../distributions/{id}/execute | operator | run now |
| POST | .../distributions/{id}/dry-run | operator | preview actions |
| GET | .../distributions/{id}/rollback-candidates | viewer | list retained versions + eligibility (Rollback) |
| POST | .../distributions/{id}/rollback | operator | optional {"artifact_id"} body; 409 when unavailable; rate-limited to 5 requests/minute per project (Rollback) |
Project — discovery
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/discovery-sources | read: viewer · writes: admin | Sources |
| POST | .../discovery-sources/{id}/scan | operator | trigger immediate scan |
| GET | /projects/{projectId}/discovery/certificates | viewer | Inventory |
| GET | /projects/{projectId}/discovery/endpoints | viewer | endpoint-level list (edge_role = edge / origin on rows from a proxied cloud-DNS record) |
| GET/PATCH | /projects/{projectId}/discovery/findings (& /{id}) | viewer (list) / operator (status) | Findings |
| GET | .../discovery/certificates/{fingerprint}/manage | operator | Manage |
| GET | /projects/{projectId}/discovery/summary | viewer | dashboard numbers |
Project — notifications
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/notification-channels | admin | Channels |
| POST | .../notification-channels/{id}/test | admin | delivery probe |
| GET/POST/PATCH/DELETE | /projects/{projectId}/notification-rules | admin | Rules |
| GET | /notification-templates, /notification-templates/defaults | any | Templates |
| POST/PATCH/DELETE | /notification-templates, /notification-templates/{id} | admin | Templates |
| GET | /projects/{projectId}/notification-history | viewer | History |
Project — operations
| Method | Path | Role | See |
|---|---|---|---|
| GET | /projects/{projectId}/jobs | viewer | Jobs |
| GET | /projects/{projectId}/jobs/{id} | viewer | job detail |
| GET | /projects/{projectId}/jobs/{id}/logs | viewer | stream logs |
| POST | /projects/{projectId}/jobs/{id}/retry | admin | retry a failed job |
| POST | /projects/{projectId}/jobs/{id}/cancel | admin | cancel a pending / in-progress job |
| GET/POST/DELETE | /projects/{projectId}/domain-trackings, /{id} (no PATCH) | operator to write | Domain tracking |
| POST | .../domain-trackings/{id}/check | operator | trigger WHOIS refresh |
| GET/POST | /projects/{projectId}/bulk-actions | operator | Bulk |
| GET | /projects/{projectId}/approval-requests | project admin | Approvals |
| GET | /approval-requests/my, /approval-requests/{id} | any | Approvals |
| POST | /approval-requests/{id}/{approve,reject,execute,retry,cancel} | scoped by action | Approvals |
| GET | /downloads/{token} | authenticated (token bearer) | Not project-scoped. Redeems the single-use token minted when an approved download request is executed — Download |
Project — dashboards
| Method | Path | Role | See |
|---|---|---|---|
| GET | /projects/{projectId}/dashboard/summary | viewer | Summary |
| GET | /projects/{projectId}/dashboard/trends | viewer | time-series renewals / distributions |
| GET | /projects/{projectId}/dashboard/readiness-47day | viewer | 47-Day |
Encryption & KEK
KEK mutations are CLI-only by design — nothing over HTTP can start, cancel or undo a rotation. See CLI → kek. One read-only endpoint exists, and it is what Settings → KEK Versions renders:
| Method | Path | Role | Purpose |
|---|---|---|---|
| GET | /settings/kek-status | admin | Keystore versions with per-version record counts and fleet load-state, the active and recent rotations, fleet mismatch, and keystore drift. See KEK rotation. |
record_count is nullable: null means the count could not be taken, which is not the same as 0.
In-app API docs
The web UI ships an interactive API reference at /api-docs — every endpoint with
its parameters, roles, and example payloads, always matching the running version.
There is currently no machine-readable OpenAPI export; script against the endpoint
tables above using a Bearer access token.