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.
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.
Root routes (outside /api/v1)
| Method | Path | Role | See |
|---|---|---|---|
| GET | /healthz | anonymous | Liveness: {"status":"ok"} while the process answers |
| GET | /readyz | anonymous | Readiness: pings MongoDB — {"status":"ok","db":"ok"}, 503 {"status":"error","db":"unavailable"} when the database does not answer |
| GET | /metrics | anonymous, or Authorization: Bearer <token> | Prometheus metrics. Only while telemetry.metrics.enabled is true (the default); when telemetry.metrics.token is set the bearer token is required (401 otherwise). The bundled nginx does not publish it — scrape the backend directly, from a trusted network |
| GET | /.well-known/acme-challenge/{token} | anonymous | HTTP-01 key authorization (text/plain, 404 for an unknown or expired token); 300 requests/minute per IP — HTTP-01 |
Authentication & user
| Method | Path | Role | See |
|---|---|---|---|
| POST | /auth/login | anonymous | Login |
| POST | /auth/logout | any | Logout. Ends the session the access token belongs to; an access token from before 1.7.0 carries no session id, so then only the refresh token in the cookie or the body (refresh_token) is revoked |
| POST | /auth/refresh | any | Refresh flow. 401 SIGN_IN_METHOD_UNAVAILABLE when the account's sign-in method is no longer open to it (Sign-in methods → Sessions); 503 when the session could not be checked — the refresh token is not consumed, retry |
| 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) | 10 requests/minute per user (shared by the two routes); 2FA |
Sign-in & SSO
Browser-facing sign-in routes (public, rate-limited per IP, no CSRF token — the flow is protected by its state, PKCE / nonce and a per-sign-in browser-binding cookie, cap_sso_<hash> — __Host-cap_sso_<hash> over https). See Sign-in methods.
| Method | Path | Role | See |
|---|---|---|---|
| GET | /auth/sign-in-options | anonymous | What the sign-in page shows: password_form (local sign-in is on, or LDAP sign-in is on and LDAP is configured), the providers with a button (slug, name, preset, icon, label) and domain_routing (some provider has e-mail domains). 600 requests/minute |
| POST | /auth/sso/discover | anonymous | {email} → {slug} of the provider whose e-mail domains contain the address; 404 when none. The domains are never listed. 120 requests/minute |
| GET | /auth/sso/{slug}/start | anonymous | Redirects to the identity provider (return_to: a path inside CertAutoPilot). A request to another host than the public URL is first redirected to the public URL. 300 requests/minute |
| GET | /auth/sso/{slug}/callback | anonymous | OIDC / GitHub answer; redirects to the return_to given at start (default the dashboard), /login?step=otp_verify / otp_setup when two-factor follows, or /login?sso_error=<code> |
| POST | /auth/sso/{slug}/acs | anonymous | SAML assertion consumer service (HTTP-POST); same redirects |
| GET | /auth/sso/{slug}/metadata | anonymous | SAML service-provider metadata (also the SP entity ID) |
| GET | /auth/sso/{slug}/slo | anonymous | Where the identity provider's SAML LogoutResponse lands (redirects to /login); an incoming LogoutRequest is answered 400 (IdP-initiated sign-out is not supported) |
Owner routes (SSO providers):
| Method | Path | Role | See |
|---|---|---|---|
| GET | /settings/sign-in/presets | owner | The provider catalogue: each type with its protocols, input fields, steps at the provider, restrictions and whether it is lab-verified |
| GET/POST | /settings/sign-in/providers | owner | List (with user_count, redirect_uri or sp_entity_id / acs_url / sp_logout_url) / create. Secrets and private keys are never returned. 400 VALIDATION_ERROR (unknown type, bad field, slug taken, an open provider with automatic account creation and no restriction, personal Microsoft accounts, IdP sign-out without a single logout service, SAML without an https public URL…); 409 CLUSTER_UPGRADE_REQUIRED enabling a provider while an older node runs |
| GET/PUT/DELETE | /settings/sign-in/providers/{id} | owner | Read / replace (the type, protocol and slug cannot change; an omitted client_secret keeps the stored one) / delete. DELETE is 409 PROVIDER_IN_USE while accounts use the provider |
| POST | /settings/sign-in/providers/test-draft | owner | Test connection for an unsaved provider (same body as create); returns {ok, error, discovered} (discovered: the OIDC endpoints and algorithms read) |
| POST | /settings/sign-in/providers/{id}/test | owner | Test connection for a saved provider |
| POST | /settings/sign-in/providers/saml-metadata | owner | Read SAML metadata (metadata_url + ca_cert, or metadata_xml; entity_id picks one identity provider from a document that lists several) and return the entity ID, URLs and signing certificates |
| POST | /settings/sign-in/providers/{id}/test-login | owner | Start a test sign-in: returns the identity-provider url; after the sign-in the browser returns to the provider page with ?test=<result id>. 400 SSO_<reason> when it cannot start |
| GET | /settings/sign-in/test-results/{resultId} | owner | A test sign-in's result (only for the owner who started it, kept 10 minutes): outcome create / sign_in / link / refused / failed, reason, the identity, username, e-mail, groups and every claim |
| POST | /settings/sign-in/providers/{id}/sp-certificate | owner | SAML service-provider certificate rotation: {action: "prepare"} publishes a next certificate beside the current one, {action: "switch"} makes it current |
| PUT | /users/{id}/sign-in-method | owner | Move an account (without subject, the first sign-in with the same username and the account's verified e-mail links it within 7 days): {method, provider_id, subject, password} — method is local, ldap or sso. Ends the account's sessions. 400 for your own account, a missing password, LDAP not configured or an unknown provider; 409 IDENTITY_TAKEN when another account already has that identity; 409 RESOURCE_CONFLICT while another change of an organization owner is in progress; 422 NO_REACHABLE_OWNER when no other owner could sign in afterwards |
Organisation / admin
| Method | Path | Role | See |
|---|---|---|---|
| GET | /status, POST /setup | anonymous | first-run state and the one-time initial-owner setup (/setup: 5 requests/minute per IP) |
| GET | /users/resolve | any | resolve user ids to display names |
| GET/POST | /users | owner | Users |
| GET/PUT | /users/{id}/roles | owner | Users. A project role may carry scope: "granted" — Resource grants; 409 CLUSTER_UPGRADE_REQUIRED while a node runs an older version. GET also returns inherited: the roles the user has through user groups, each with via_group. An empty list is accepted (the user keeps only what its groups give) |
| GET | /users/{id}/groups | owner | the user's groups, each with the sources of the membership (manual, ldap, sso:<provider id>) |
| POST | /users/{id}/reset-password | owner | Users |
| PATCH/DELETE | /users/{id} | admin | Users. Deactivating or deleting (and removing the owner role through PUT /users/{id}/roles) the last owner who can sign in without an identity provider is 422 NO_REACHABLE_OWNER; 409 RESOURCE_CONFLICT while another change of an organization owner is in progress (try again) |
| GET/PATCH | /auth/me/profile | any (self) | Profile |
| POST | /auth/me/change-password | any (self) | 5 requests/minute per user |
| PATCH | /auth/me/preferences | any (self) | e.g. favourite project |
| GET | /debug/pprof, /debug/pprof/{name} | owner | Go runtime profiles (goroutine dump, heap, CPU) — see Runbook: stuck jobs |
| GET/PUT | /settings/ldap · POST /settings/ldap/test, /settings/ldap/test-filter | owner | LDAP. default_role: viewer (default) or none; anything else is 400. The bind password is stored encrypted; an empty one keeps the stored password for the same host, a host change without it is 400, and so is an empty one when the stored password can no longer be decrypted. Clearing the host is 422 NO_REACHABLE_OWNER when no owner could sign in without LDAP. test-filter with filter_type: "group" also returns group_names (the Group attribute of each entry) and a warning when the entries lack it |
| GET/PUT | /settings/sign-in | owner | Sign-in switches (while an SSO provider is enabled the public URL cannot be cleared or made unusable for it — 400). GET returns {public_url, local_login_enabled, ldap_enabled, ldap_configured}; PUT takes public_url (an http(s)://host[:port] origin with no path, query or fragment; empty clears it), local_login_enabled and ldap_enabled (both required). With local sign-in off, org owners with a local account can still sign in with their password. 400 VALIDATION_ERROR for a bad URL; 422 NO_REACHABLE_OWNER when no organization owner could sign in afterwards; 409 CLUSTER_UPGRADE_REQUIRED turning local or LDAP sign-in off while an older process is running |
| GET/PUT | /settings/otp-policy | owner | OTP policy |
| GET/PUT | /settings/syslog · POST /settings/syslog/test | admin | Syslog |
| GET/PUT | /settings/general | admin | — |
| GET | /settings/scheduler-status, /settings/scheduler-status/history | admin | Scheduler |
| GET | /settings/cluster-instances | admin | Cluster |
| GET | /system/app-update | admin | A newer release on CertAutoPilot OS: {appliance, current_version, latest_version, update_available}. Any other install type answers appliance: false and makes no outbound call; a failed check keeps the last answer |
| GET/POST/PATCH/DELETE | /discovery-dns-providers (& /{id}) | admin | Cloud DNS discovery |
| POST | /discovery-dns-providers/{id}/test | admin | connection test; 20 requests/minute |
| GET/PUT | /settings/license | admin | License |
| PUT | /settings/license/api-key | admin | License |
| PUT/DELETE | /settings/license/offline | admin | License; DELETE is 409 LICENSE_NOT_OFFLINE when no offline license is active |
| POST | /settings/license/validate | admin (10/min per user) | License — checks now; without a key to check it answers success:false |
| GET | /license/status, /license/usage | any | License status |
| GET | /audit-logs, /audit-logs/{id} | admin (org scope). The project-scoped /projects/{id}/audit-logs, its /export and one entry /projects/{id}/audit-logs/{entryId} are readable by any project viewer (a user limited to granted resources sees the same entries as in the list; 404 otherwise). Lists and exports take action_prefix (repeatable), actor, resource_type, resource_id. | Audit logs |
| GET | /audit-logs/export | admin | format (json default, csv), since, until (RFC3339) and the list filters; newest first, at most 10,000 entries per export (the project export too) — Audit export |
| POST | /audit-logs/verify | owner | Verify the chain; 1 request/minute. Query since (RFC3339), from_seq and limit (positive integers, else 400; limit at most 1000); continue with from_seq=<next_seq>. Each of breaks carries seq and reason (checksum_mismatch, anchor_mismatch, missing_predecessor) |
| GET/POST/PATCH/DELETE | /organizations (& /organizations/{id}) | GET: any authenticated user · writes: admin | — |
| GET/POST/PATCH/DELETE | /projects (& /projects/{id}) | list: any · read one: project viewer · create and delete: owner · edit: project admin | — |
| GET | /ca-providers | any | catalogue of ACME CAs the backend knows by default |
| PATCH | /ca-providers/{id}/environments/{envKey} | owner | repoint one environment's directory URL |
| GET | /chain-certificates, /chain-certificates/{id} | any | the chain catalogue — Certificate chain |
| POST/DELETE | /chain-certificates, /chain-certificates/{id} | admin | add one certificate (422: not one CA certificate, self-signed root, expired, duplicate, revoked) / remove (409 while a certificate uses it) |
| POST | /chain-certificates/ccadb/search, /chain-certificates/ccadb/import | admin | find CCADB certificates that extend a chain / add them; 409 when the lookup is switched off, 502 CCADB_UNAVAILABLE |
| GET | /modules/types | any | the distribution module catalogue |
| GET | /dependencies?type=&id= (also /projects/{projectId}/dependencies) | any / project viewer | dry-run of the delete-dependency check |
User groups
Organisation-wide; every route is owner only. Rules: User groups.
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST | /groups | owner | list (paginated, ?search=) / create {name, description?, external_mappings?: [{provider, value}]} (provider: ldap or sso:<provider id>); a duplicate name (regardless of case) is 400 |
| GET/PATCH/DELETE | /groups/{id} | owner | one group (member_count included); DELETE removes its roles, memberships and grants |
| GET/PUT | /groups/{id}/members | owner | {items: [{user_id, name, sources}]}; PUT {user_ids} replaces the hand-added members (members LDAP added are kept); at most 5000 |
| GET/PUT | /groups/{id}/roles | owner | {roles: [{project_id?, role, scope?}]}; owner and scope: "granted" without a project are 400; dropping a project's role removes the group's grants there unless an org-wide role is kept; a group's grants count only while its role in that project is limited to granted resources |
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}/acme-cas | read: viewer · writes: admin | custom ACME CAs; 422 on a refused directory URL / CA certificate, 409 ACME_CA_IN_USE on a URL change with accounts, 409 CLUSTER_UPGRADE_REQUIRED on create while a node is older |
| POST | /projects/{projectId}/acme-cas/{id}/test | admin | read the directory with the CA's own trust and network rule |
| GET | /projects/{projectId}/acme-cas/{id}/usage | viewer | accounts registered on this CA |
| GET | /projects/{projectId}/reports/pdf | operator | PDF report built with the caller's access; sections (repeatable or comma-separated: certificates, distribution, readiness_47day, discovery; empty = all), expiring_within_days (1–365, default 30), timezone (IANA, default UTC); 400 on an unknown value; rate limit 10/min per user and 30/min per project |
| GET/POST | /projects/{projectId}/reports/subscriptions | operator | scheduled reports; an operator (and a project admin limited to granted resources) lists and creates only their own, a whole-project admin sees every one; adding extra_recipients needs a whole-project admin (403 otherwise) on a report whose owner is a whole-project admin (422 otherwise); 422 on a bad schedule (incl. timezone Local), the owner's 50th report in the project, a non-SMTP channel or one the owner cannot see, no recipient, or "send to me" without a profile e-mail — the last three only while the report is active; 400 on a malformed body (a decimal day count is named); 409 CLUSTER_UPGRADE_REQUIRED while an older node runs; create/save/delete 30/min per project |
| GET/PUT/DELETE | /projects/{projectId}/reports/subscriptions/{id} | operator (own) · whole-project admin (any) | PUT sends the whole object (an omitted enabled keeps the stored value, expiring_within_days 0 = 30; the same schedule keeps the pending send time; a changed schedule abandons an unsent earlier one); anyone who may edit can remove extra_recipients; turning on a deactivated owner's report is 422; 404 for another user's subscription |
| POST | /projects/{projectId}/reports/subscriptions/{id}/send | operator (own) · admin (any) | 202 + job_id: sends now, the schedule is unchanged; 409 CLUSTER_UPGRADE_REQUIRED while an older node runs; rate limit 5/min per user and 15/min per project |
| GET/POST/PATCH/DELETE | /projects/{projectId}/msca-connections | read: viewer · writes: admin | MSCA; transport (rpc / ces) is fixed at create; a POST of an RPC connection is 409 CLUSTER_UPGRADE_REQUIRED while an older node runs; a PATCH moving the CEP/CES endpoints, any RPC setting (CA server, CA name, domain, domain controller, directory TLS or pin, KDC, template source), the authentication, the user name of an RPC connection, or TLS settings without the password is 422 MSCA_CONNECTION_CREDENTIAL_REQUIRED unless you entered it or are an organization owner |
| POST | /projects/{projectId}/msca-connections/{id}/sync-templates | admin | refresh the template catalogue |
| POST | /projects/{projectId}/msca-connections/{id}/test | admin | probe CES / CEP, or the CA over RPC (and the directory entry) |
| POST | /projects/{projectId}/msca-connections/discover | admin, 20/min per project | list the forest's enterprise CAs and their templates from Active Directory without saving anything; an untrusted domain-controller certificate answers 400 MSCA_TLS_VALIDATION with presented_fingerprint; connection_id uses that saved connection's TLS CA certificate |
| GET | /projects/{projectId}/msca-connections/{id}/usage | viewer | certs referencing this connection |
| GET | /projects/{projectId}/ca-connector-vendors | any member | the shipped CA connector vendors: auth schemes (fields carry secret, required, multiline, generated), capabilities, default products, listed (offered for new connections), zone_optional (the vendor validates domains on its account, so a certificate needs a zone only for domains not validated there yet), default_base_url |
| GET/POST/PATCH/DELETE | /projects/{projectId}/ca-connections (& /{id}) | read: viewer · writes: project admin | CA connectors; credential fields are write-only, PATCH merges them; base_url may be left empty on create when the vendor has a default_base_url; a create for a vendor that is not offered for new connections is 422 CA_VENDOR_NOT_OFFERED; a GlobalSign create is 409 CLUSTER_UPGRADE_REQUIRED while an older node runs; responses carry client_cert (subject, issuer, not_after, csr_pending, csr_pem) for a vendor that authenticates with a TLS client certificate; PATCH is 409 CA_CONNECTION_CHANGED when the stored credentials changed after it read them (another save or a Generate CSR in between — reload and save again); DELETE 409 while a certificate references the connection |
| POST | /projects/{projectId}/ca-connections/{id}/test | project admin | vendor probe that cannot place an order; the message notes an mTLS client certificate that has expired or expires within 30 days |
| POST | /projects/{projectId}/ca-connections/{id}/client-csr | project admin, 10/min per project | makes a new RSA-2048 mTLS client key (kept encrypted, never returned) and answers {csr, connection}; the current key keeps working until the certificate issued for the CSR is pasted into the connection (PATCH with auth.mtls_cert). 422 CA_CONNECTION_NO_CLIENT_CERT for a vendor that uses no client certificate. 409 CA_CONNECTION_CHANGED when the credentials changed meanwhile. Audit CA_CONNECTION_CSR_GENERATED — GlobalSign Atlas |
| GET | /projects/{projectId}/ca-connections/{id}/account | operator, 60/min per project | the vendor account read live with read-only vendor calls: policy (key_types, key_algorithm, key_sizes_decided_by_vendor (ECDSA: the policy names no curves in CertAutoPilot's terms), max_dns_names, min_dns_names, allowed_suffixes, key_format, public_key_signature, max_ip_addresses, max_validity_seconds, hash_algorithms, key_usages[{name, rule, requested}], extended_key_usages, subject_required/subject_optional, issuer_expires_at), issued, revoked, quota (-1 = no limit reported), domains[{ref, domain, status, expires_at, verified_at, method, last_error}] (ref = the vendor's id of the validation, used by the domain routes below), domains_unavailable (the domain list could not be read), errors (parts that could not be read), read_at, cached. Cached a minute per connection version; ?refresh=true skips it. 404 unknown connection, 422 CA_ACCOUNT_UNSUPPORTED for a vendor without account reading, 502 (upstream: true, code) when the vendor refuses — GlobalSign Atlas |
| GET | /projects/{projectId}/ca-connections/{id}/issued?days= | operator, 60/min per project (shared with /account) | the certificates the vendor account issued in the last days (default 30, 1–365: out of range 422, not a number 400) — through CertAutoPilot or not: `{from, to, certificates[{serial, not_before, not_after, revoked, status: active |
| GET | /projects/{projectId}/ca-connections/{id}/account/domains/{ref} | operator, 60/min per project (shared with /account and /issued) | one domain validation of the vendor account: the /account domain fields plus authorization_domains[] (where its proof may be published) and emails[] (approval addresses). 404 when the account holds no validation under ref (also for a value that is not a vendor id — nothing is sent then); 502 (upstream: true) when the vendor fails |
| DELETE | /projects/{projectId}/ca-connections/{id}/account/domains/{ref} | project admin, 10/min per project | removes the domain validation from the vendor account (an already removed one counts as removed; a value that is not a vendor id is 404). 409 CA_DOMAIN_IN_USE while a certificate waits for it; 502 when the vendor is checking it right now (CLAIM_CHECK_RUNNING) or refuses. Audit CA_ACCOUNT_DOMAIN_REMOVED |
| POST | /projects/{projectId}/certificates/{id}/ca-validation/cancel | operator | stops the domain validation of a CA connector certificate while nothing has been ordered: the validation state closes, its queued jobs are cancelled, a record CertAutoPilot published is cleaned up, and the certificate returns to its earlier status (re-issue → where it started, renewal → renewal_failed, first issuance → pending, the last two with DOMAIN_VALIDATION_STOPPED). 409 CA_VALIDATION_BUSY (an order step is running — retry) / CA_VALIDATION_NOT_WAITING (nothing to stop, or an order exists); 422 for a certificate that is not a CA connector one. Audit CERT_VALIDATION_STOPPED. DELETE of such a certificate stops its validation the same way first — GlobalSign Atlas |
| POST | /projects/{projectId}/certificates/{id}/ca-order/discard | admin | discards a CA connector order request the vendor never answered; body {"state_id"} names it. The certificate returns to its earlier status (first issuance → pending, renewal → renewal_failed, re-issue → where it started) with ORDER_REQUEST_DISCARDED, queued order jobs are cancelled, the previous key becomes current again, and an expired certificate leaves automatic renewal. The next request is a new one — it uses quota for a second certificate if the vendor did create one for the discarded request; Re-issue asks again safely instead. 404 unknown state_id, 409 CA_ORDER_BUSY / CA_ORDER_NOT_UNCONFIRMED, 10/min per project. Audit CERT_ORDER_REQUEST_DISCARDED — GlobalSign Atlas |
| GET | /projects/{projectId}/ca-validation-domains?name=… | any member | the domains that may be validated on a vendor account (ca_validation_domain) for a certificate with the given names (name, repeatable, ≤1000): the first name and each parent the create accepts for every name — never a public suffix, most specific first; an empty list when the names share no parent. Nothing is asked from the vendor |
| POST | /projects/{projectId}/certificates/{id}/ca-validation/check | operator, 20/min per project | runs the waiting domain-validation check of a CA connector certificate now instead of at its next scheduled time (moves the existing check job forward — nothing is enqueued, nothing bought by itself); answers {check: {running, job_id}, message}. 409 CA_VALIDATION_NOT_WAITING when no validation waits (or the order is already being placed, or no check is scheduled — it is started again within 90 minutes); 422 for a certificate that is not a CA connector one. Audit CERT_VALIDATION_CHECK_REQUESTED — Checking now |
| GET | /projects/{projectId}/certificates/{id}/ca-validation/emails | operator, 30/min per project | for a CA connector certificate validating its domain by e-mail (ca_domain_validation: email): per pending validation {domain, ref, emails[], email_sent_to?, email_sent_at?} as checks[], the addresses read live from the vendor. 409 CA_VALIDATION_NOT_WAITING when no validation waits, 422 when the certificate does not use e-mail — GlobalSign Atlas |
| POST | /projects/{projectId}/certificates/{id}/ca-validation/email | operator, 5/min per project | body {ref, email_address}: the vendor sends the approval e-mail of that validation to the address (one it lists). 422 CA_VALIDATION_EMAIL_NOT_ALLOWED (nothing sent), 409 CA_VALIDATION_NOT_WAITING, 502 when the vendor refuses. Audit CERT_VALIDATION_EMAIL_SENT |
| GET | /projects/{projectId}/ca-connections/{id}/usage | viewer | certs referencing this connection |
Project — DNS
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/dns-credentials | read: viewer · writes: admin | DNS providers; a PATCH moving where the secret goes (nameserver, API URL, host, KDC, TLS checks) without the secret is 422 DNS_CREDENTIAL_SECRET_REQUIRED unless you entered it or are an organization owner |
| POST | /projects/{projectId}/dns-credentials/{id}/test | admin | smoke-test the credential (bounded at 90 s on the server; a test record it created is still cleaned up) |
| GET | /projects/{projectId}/dns-credentials/{id}/usage | viewer | zones / certs referencing this credential |
| GET/POST/PATCH/DELETE | /projects/{projectId}/zones | read: viewer · writes: admin | Zones; a zone takes domains (one or more, each in one zone of the project — 409 ZONE_DOMAIN_TAKEN) and an optional name; PATCH domains replaces the list, a domain a certificate still uses cannot be removed (409 ZONE_DOMAIN_IN_USE); more than one domain 409 CLUSTER_UPGRADE_REQUIRED while an older node runs |
| POST | /projects/{projectId}/zones/match | viewer | suggests a zone for each name ({"domains": [...]}, at most 1000): the longest visible zone the name is under, with the zone's domain the name is under (zone_domain), the zone's zone_label, its credential's provider, sequential, in_process_cleanup and apex; 120/min per user; read-only, not audited (Zones) |
| GET | /projects/{projectId}/zones/{id}/certificates | viewer | certificates that validate a name through this zone (as their zone or as one name's zone) |
| GET | /projects/{projectId}/zones/{id}/rate-limits | viewer | weekly budget + projection |
Project — certificates
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/certificates | read: viewer · create / PATCH: operator (create: 10 requests/minute per project) · DELETE: admin | Issue; create and PATCH take chain — Certificate chain; create takes domain_zones for names in several zones — ACME automatic DNS: every name with its zone_id; a CA connector whose vendor validates domains on its account (GlobalSign Atlas, automatic DNS): only the names that have a zone (GlobalSign: names in several zones) — 409 CLUSTER_UPGRADE_REQUIRED while an older node runs (Names in several zones); create takes issuer_type acme / msca / ca_connector (+ ca_connection_id, optional ca_product_code) — a connector certificate needs a zone with a DNS credential (422 ISSUER_REQUIRES_ZONE / ISSUER_REQUIRES_DNS_CREDENTIAL) unless its vendor validates domains on its account (zone_optional in the vendor catalogue); such a vendor also takes ca_domain_validation (dns default, manual_dns, http, email — the last three with no zone_id, 400 otherwise) and ca_validation_domain (the name or a parent of it, never a public suffix; 400) — Proving a domain yourself |
| GET | /projects/{projectId}/certificates/export | viewer | CSV inventory export |
| GET | /projects/{projectId}/certificates/{id}/detail | viewer | certificate with account / artifact / key history, recent jobs, risk_score — Risk — and chain (the current version's chain of trust, leaf first, public certificates only; each intermediate/root entry carries its own pem); ca_connection and the latest ca_order_state for a connector certificate |
| GET | /projects/{projectId}/certificates/{id}/discovery-sightings | viewer | where discovery has seen this certificate |
| GET | /projects/{projectId}/certificates/{id}/chain-options | viewer | the chain choice, the current certificate, the served and the CA's chain with the root each ends at, the notes, the chains the CA offered — Certificate chain |
| GET | /projects/{projectId}/certificates/{id}/chain-preview | viewer | an unsaved chain choice (preferred_anchor, repeatable extension_id, at most 4) judged against the current version: the chain it would serve and, for every catalogue entry, whether it links — read-only — Certificate chain |
| GET | /projects/{projectId}/acme-accounts/{id}/chain-anchors | viewer | the chains (by root) the account's CA offered on the project's certificates; key_type limits them to certificates of the same key algorithm |
| 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 | A new key and a new certificate, also for an active ACME / AD CS certificate; a failed re-issue returns to the previous status; 409 while a renewal is in flight — Reissue |
| POST | /projects/{projectId}/certificates/{id}/rekey | operator | An active CA-connector certificate whose vendor offers rekey (GlobalSign Atlas, catalogue rekey): the vendor issues a copy with a new key, the same names, no domain validation; the current certificate stays valid there. Queued once (manual_rekey:<id>, never retried), stored as a new version. Asks the same approval as Re-issue (the request carries params.rekey: true; 202 then). 422 ISSUER_UNSUPPORTED_OPERATION (no rekey), 400 not active, 409 an order in flight or a revocation pending. Audit CERT_REKEY_REQUESTED — Renew, Re-issue and Rekey |
| POST | /projects/{projectId}/certificates/{id}/reissue/cancel | operator | Cancel a manual-DNS re-issue waiting for its TXT records; the current certificate keeps its status and key — Reissue |
| POST | /projects/{projectId}/certificates/{id}/revoke | operator (an operator's revocation becomes an approval request when the project's approval policy gates revocation for them) | Revoke; 422 ISSUER_UNSUPPORTED_OPERATION when the issuing CA cannot revoke from CertAutoPilot (AD CS, imported, a CA connector whose vendor has no revoke call — GlobalSign Atlas certificates can be revoked) |
| POST | /projects/{projectId}/certificates/{id}/download | operator | Returns the payload directly. Body: format (pem default, bundle, cert, fullchain, chain, key, all, pfx, der, jks), password (pfx / jks only), alias (jks only), pfx_encryption modern (default) | legacy (pfx only — 400 for another value or format), artifact_id (a retained version). 202 {approval_request, message} when the project's approval policy gates the download for the caller (the format, alias and pfx encryption are kept with the request, never the password) — Download |
| POST | /projects/{projectId}/certificates/{id}/validate | operator | Manual DNS — submit for validation |
| GET | /projects/{projectId}/certificates/{id}/dns-check | operator | Manual DNS — check TXT propagation |
| GET | /projects/{projectId}/certificates/{id}/timeline | viewer | Timeline (cursor-paged: cursor, limit default 50, max 100) |
| GET | /projects/{projectId}/certificates/{id}/jobs | viewer | jobs scoped to this cert |
| GET | /projects/{projectId}/certificates/{id}/graph | viewer | Dependencies |
| GET | /projects/{projectId}/certificate-policy | operator | Policy |
| PUT/DELETE | /projects/{projectId}/certificate-policy | admin | Policy |
| GET | /projects/{projectId}/approval-policy | any project member | The project's approval policy per operation (off, all, selected users/groups); a project without a saved policy returns the defaults — Approval workflow |
| PUT | /projects/{projectId}/approval-policy | org owner | Replaces the policy. 400 on validation, 409 RESOURCE_CONFLICT when it changed since it was read, 409 CLUSTER_UPGRADE_REQUIRED while an older node is live |
| DELETE | /projects/{projectId}/approval-policy | org owner | Removes the saved policy; the project falls back to the defaults |
Project — distribution
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/modules | read: viewer · writes: operator | Modules |
| GET | /projects/{projectId}/modules/{id}/usage | viewer | distributions using this module |
| POST | /projects/{projectId}/modules/{id}/health | admin | live health check, bounded at 100 s; per-target duration_ms, and a not checked row for a target the check had no time left for — Health checks |
| 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 / all-bindings / app-pools / placement-preview, Kubernetes namespaces / secrets / workloads, Vault mounts / secrets, Azure Key Vault certificates, Exchange servers, Cloudflare zones / custom-certificates, AWS ACM certificates, PAN-OS vsys / certificates, Elchi projects, FortiWeb policies / sni-groups / sni-members / multi-certificates / certificates / intermediate-groups / placement-preview — what a deploy would do, from its own plan; takes the same placement overlay with for required and the FortiWeb placement fields, and an optional certificate_id, FortiGate certificates / vips / ssl-profiles, A10 partitions / templates / certificates / sni-entries / placement-preview (the deploy plan; placement overlay with for and cert_name / templates / sni, optional certificate_id), MerlinCDN distributions / canonical-names); read-only, 60/min per project, 500 rows max; bounded at 28 s on the server (90 s for Exchange servers, 100 s for an IIS placement preview over every site or several sites); the IIS placement-preview also takes a placement overlay (the placement being edited; for: "override" or "target" says whether it is a distribution override or a whole target placement — an override may carry apply_mode: "selector") and certificate_id (+ verify_binding_names) to judge each binding as a dry run does (IIS, Kubernetes, Vault, Azure Key Vault, Exchange, Cloudflare, AWS ACM, PAN-OS, FortiGate) |
| GET/POST/PATCH/DELETE | /projects/{projectId}/credentials | read: viewer · writes: admin (they hold secrets); the list takes ?credential_type=a,b (up to 20 types, 400 above that; unknown types match nothing); allowed_hosts lists where it may be sent and secret_set_by_name who entered the secret — see credential hosts (422 CREDENTIAL_HOST_NOT_ALLOWED); GET …/credentials/{id}/host-check?host= (viewer, at most 20 host values — 400 above that) answers before a target save whether the hosts are allowed. Create: 10 requests/minute per project. PATCH: 422 CREDENTIAL_SECRET_REQUIRED (a WinRM-type secret's KDC / domain changed without the password) and 422 CREDENTIAL_REF_CHANGE_NOT_ALLOWED (a store-backed credential pointed at another secret_ref) unless you entered the secret (set the store up) or are an organization owner; an update that drops hosts returns them once as removed_hosts | Module creds |
| POST | /projects/{projectId}/credentials/{id}/test | admin | resolve the credential; reports its shape, never its value; 20 requests/minute |
| 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; create 10 requests/minute per project. 422 on validation, 422 CREDENTIAL_HOST_NOT_ALLOWED (the auth credential may not be sent to the store's address) or CREDENTIAL_TLS_CHANGE_NOT_ALLOWED (weakened TLS check) unless you entered the auth credential's secret or are an organization owner; DELETE 409 while a credential reads through it |
| POST | /projects/{projectId}/secret-stores/{id}/test | admin | live connectivity + auth check; 20 requests/minute |
| GET/POST/PATCH/DELETE | /projects/{projectId}/targets | read: viewer · writes: operator | Targets. The list takes target_type (one type or several, comma-separated), ids (comma-separated, at most 100 — only these; an empty ids= answers nothing) and search (name and the address the target dials); 400 over 20 types or 100 ids, or for a target_type that is not a target type. Create is 403 target_limit_reached at the licence's target limit. 422 CREDENTIAL_HOST_NOT_ALLOWED when the credential may not be sent to the target's host, 422 CREDENTIAL_TLS_CHANGE_NOT_ALLOWED when the change weakens the TLS check a bound credential is sent under (both unless you entered the credential's secret or are an organization owner); 400 when ca_cert / tls_fingerprint_sha256 are set with use_ssl off (F5, NetScaler) or ca_cert without ssl_verify |
| POST | /projects/{projectId}/targets/bulk/check | operator | Bulk add, dry check: body { target_type: ssh|winrm|iis, rows: [{name, host}], target_group_id? } (1–500 rows); answers each line's status (new, duplicate, exists with the existing target_id, invalid) with a detail, new (how many would be created) and, with a group, existing_to_group (existing targets that would join it; their detail says will be added to the group or already in the group). Creates nothing, not audited; 120/min per user |
| POST | /projects/{projectId}/targets/bulk | operator | Bulk add: body { target_type, template, rows, target_group_id? } — template is a create-target body whose name and address are ignored. 200 with one result per line (created + target_id, duplicate, exists, invalid, failed, not_attempted), created, group_added / group_error, group_added_new / group_added_existing; lines are independent. With target_group_id, servers of the list that are targets already join the group too (exists rows say added to the group or already in the group). 202 with one approval request for the whole list when the caller needs approval — for creating targets, or for editing target_group_id (409 while the same list is already waiting, 400 when it holds nothing new and, with a group, no existing target outside it, or its template can make no target). 400 for another target type, no rows, more than 500 rows, no template, validation endpoints in the template, an unknown group or one of another type; 403 ACCESS_DENIED when the caller is not at least operator on target_group_id (nothing is created); 403 target_limit_reached at the licence limit; 30/min per project |
| GET | /projects/{projectId}/targets/{id}/usage | viewer | distributions / groups using this target |
| POST | /projects/{projectId}/targets/{id}/health | admin | live health check of one target — Health checks |
| GET | /projects/{projectId}/targets/host-key/awaiting, /targets/{id}/host-key | viewer | SSH host keys waiting for approval — Host-key verification |
| POST | /projects/{projectId}/targets/{id}/host-key/approve | operator | approve a presented SSH host key |
| GET/POST/PATCH/DELETE | /projects/{projectId}/target-groups | read: viewer · writes: operator | Target groups. The list takes target_type (comma-separated) and ids (at most 100) like the target list |
| GET/POST/DELETE | /projects/{projectId}/target-groups/{id}/targets | read: viewer · add / remove members: operator | group membership |
| GET/POST/PATCH/DELETE | /projects/{projectId}/path-sets | read: viewer · writes: operator | Path sets |
| GET/POST/PATCH/DELETE | /projects/{projectId}/action-sets | read: viewer · writes: operator | Action sets |
| GET | /projects/{projectId}/action-sets/{id}/variables | viewer | template-variable lint of a saved action set |
| POST | /projects/{projectId}/action-sets/variables/lint | viewer | template-variable lint of an unsaved body |
| GET/POST/PATCH/DELETE | /projects/{projectId}/variables | read: viewer · writes: operator | Variables |
| GET/POST/PATCH/DELETE | /projects/{projectId}/certificates/{id}/distributions | read: viewer · attach / edit / unlink: operator | The list response omits last_target_results (up to 200 per-target subdocs per row). Linking a certificate to a module configuration it is already linked to is 422 (one link per certificate + module configuration — edit the existing one). chain_source: "ca_default" deploys the chain as the CA delivered it instead of the certificate's chosen one (Certificate chain). target_overrides is keyed by target id, group:<target group id> (a group row — one of the module's target groups) or * (the Default row) and is replaced whole on edit (Per-distribution overrides); 422 OVERRIDE_GROUP_CONFLICT when two group rows that set a value share a target, 409 CLUSTER_UPGRADE_REQUIRED for a group row while an older node runs |
| GET | .../distributions/{id} | viewer | one distribution with its full last_target_results history |
| POST | .../distributions/{id}/execute | operator | run now; 5 requests/minute per project (shared with rollback); the job fails with lock is held while another run of the same distribution is in progress |
| POST | .../distributions/{id}/dry-run | operator | preview actions; 5 requests/minute per project; bounded at 100 s server-side (per-target duration_ms + steps say where the time went) |
| GET | .../distributions/{id}/rollback-candidates | viewer | list retained versions + eligibility (Rollback) |
| POST | .../distributions/{id}/rollback | operator | optional {"artifact_id"} body; 409 when no eligible version, 422 when a rollback or fan-out is already running, 202 when it becomes an approval request; rate-limited to 5 requests/minute per project, shared with execute (Rollback) |
Project — discovery
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/discovery-sources | read: viewer · writes: admin | Sources; source_type target_scan takes target_scan_config (target_ids, target_group_ids, linux {mode standard|everything, paths, include_trust_stores}, windows {mode, stores, paths, include_trust_stores, skip_files}, max_files_per_host, host_budget_seconds, scan_deadline_seconds; owner_user_id is set by the server) and needs admin on every target, group and group member (403 ACCESS_DENIED; an unknown or invisible one is 422); 409 CLUSTER_UPGRADE_REQUIRED while a node older than 1.7.3 is live — see Server certificate scan |
| POST | .../discovery-sources/{id}/scan | operator | trigger immediate scan; 404 for an unknown source, 400 for a paused one; 10 requests/minute per project |
| GET | .../discovery-sources/{id}/runs | viewer | scan run history; a server certificate scan run carries target_scan_counts (targets per result status, plus total) |
| GET | .../discovery-sources/{id}/runs/{runId}/targets | viewer | a server certificate scan run's result per target, sorted by name, written as each target finishes: results, total, counts (the whole run's), page, page_size; filters status (ok|failed|skipped|truncated|not_started), search (name or address); page_size 1–500; 404 for another source's run |
| GET | .../discovery-sources/{id}/health | viewer | scan health of one source: verdict (healthy, scanning, paused, never_ran, attention, failing), reasons (code, severity, text), scanning, last_run, success_rate, history, avg_duration_seconds, methods |
| GET | .../discovery-sources/{id}/certificates | viewer | certificates this source found; ca = false (default: server certificates) or true (CA certificates a server certificate scan found in trust stores and CA files) |
| GET | .../discovery-sources/{id}/ct-observations | viewer | CT monitoring observations |
| GET | .../discovery-sources/{id}/locations | viewer | where a server certificate scan found certificates: locations (target_id, target_name, target_type, host, os, kind file|store, path or store + thumbprint, format pem|der|p7b|pfx|store, fingerprint_sha256 (empty for an unread PKCS#12), bundle_index, subject, not_after, first_seen_at, last_seen_at, disappeared_at), total; filters target_id, kind, search (path, target, subject, store, thumbprint), include_gone, page, page_size (1–500) |
| GET | .../discovery-sources/{id}/endpoints | viewer | the source's endpoint rows; host and port narrow to one address (search then matches the SNI name instead of the host); rows carry cert_subject / cert_issuer / cert_not_after, and name_mismatch: true when the served certificate does not cover the row's SNI while DNS points the name at that address (a crawler-derived name DNS does not point there is never recorded) |
| GET | .../discovery-sources/{id}/endpoints/grouped | viewer | the same rows summarised per IP:port (name_count, distinct_cert_count, managed/unmanaged/failed counts, mismatch_count, methods, edge roles); total is the number of addresses; members come from /endpoints?host=&port= |
| GET | /projects/{projectId}/discovery/certificates, /discovery/certificates/{fingerprint} | viewer | Inventory; the list takes ca = false (default: server certificates), true (CA certificates no server serves, from server certificate scans) or all; each certificate carries server_count (servers — distinct address:port — serving it now, as the caller sees them) beside endpoint_count (rows), and rule_tags / rule_owner (what tag rules gave) beside the typed tags / owner; the tag and owner filters cover both (a typed owner wins). List filters added in 1.7.0: expires_from / expires_to (RFC 3339, not_after in [from, to), ≤400 days apart, not with expiring_within), risk_factor (stored reason codes, comma list), caa (ok, violation, unknown_issuer, error, unchecked), domain (a registrable domain; certificates with a SAN or CN whose registrable domain it is; not an IP or *.), trust (public, private, untrusted), serving (answering, not_answering — every server serving it failed its latest scan), no_tag=true, no_owner=true (not with tag / owner); managed takes true (CertAutoPilot's current version), false (no managed certificate claims it) or outdated (an earlier version of a managed certificate still served); invalid values are 400. Each certificate carries managed_outdated and unanswered_since (when a server serving it last answered, while every one fails). Added in 1.7.3: filter found_on=servers (certificates a server certificate scan found in a file or a Windows store) and location_count on each certificate |
| GET | /projects/{projectId}/discovery/certificates/{fingerprint}/changes | viewer | change history of one discovered certificate |
| GET | /projects/{projectId}/discovery/certificates/{fingerprint}/timeline | viewer | timeline: first_seen_at, last_seen_at, servers (≤200, most recently seen first: host, port, segments — from, from_known, to, end serving | replaced | gone | unreachable | unknown, replaced_by, last_answer_at (end unreachable: when the server last answered) — and markers of TLS-setting changes), certificates (replacing certificates still in the inventory), truncated, unplaced (changes recorded without a server); 404 when the caller cannot see the certificate |
| GET | /projects/{projectId}/discovery/certificates/facets, /discovery/tags | viewer | issuer / key-type filter options with counts; tags in use (typed and from tag rules, sorted, at most 500) |
| GET | /projects/{projectId}/discovery/certificates/export, /discovery/findings/export | viewer | Export as CSV or JSON (format), every list filter — 10/min per project |
| GET | /projects/{projectId}/discovery/certificates/{fingerprint}/endpoints | viewer | endpoints serving one discovered certificate, host and port order: at most the first 5,000, with total and truncated |
| PUT | /projects/{projectId}/discovery/certificates/{fingerprint}/annotations | operator | tags and owner |
| POST | /projects/{projectId}/discovery/certificates/{fingerprint}/import | admin | import with the private key |
| GET | /projects/{projectId}/discovery/certificates/{fingerprint}/locations | viewer | the files and Windows store entries server certificate scans found it in (sources the caller can see; at most 500, truncated); one row per place — sources scanning the same server are merged into sources (id, name); include_gone |
| POST | /projects/{projectId}/discovery/estimate | operator | estimate a source's scan size before saving; 30 requests/minute per project |
| GET | /projects/{projectId}/discovery/endpoints | viewer | endpoint-level list (name_mismatch: true on an SNI row whose served certificate does not cover a name DNS points at that address — see Sources; edge_role = edge / origin on rows from a proxied cloud-DNS record; kex_support {supported, complete, checked_at} when the source probes key-exchange groups; origin_closed: true on a failed origin row whose address never answered while the same name served a certificate at the edge — origin firewalled to Cloudflare). Filters: include_failed=true; kex_pqc = comma list of hybrid, pq (ML-KEM alone), classical, none, unknown (unknown = an unrecognised group or not recorded yet; also keeps only rows whose last scan served a certificate, failed rows excluded even with include_failed; repeated kex_pqc= parameters add up); tls_below_13=true = TLS 1.2 or older; search = part of the host, any case; fingerprint (64 hex) = the endpoints of one certificate; source = comma list / repeated, at most 100. An unknown value is 400 |
| GET | /projects/{projectId}/discovery/endpoints/export | viewer | one row per endpoint with the certificate it serves, format=csv (default) or json, streamed; the list's filters (include_failed, kex_pqc, tls_below_13, search) plus fingerprint (64 hex) and source (comma list / repeated, ≤100); a failed row names no certificate and carries last_error; 10 per minute per project (shared with the other discovery exports), audited DISCOVERY_ENDPOINTS_EXPORTED; 400 on a bad format or filter |
| GET | /projects/{projectId}/discovery/endpoints/{endpointId}/changes | viewer | what one endpoint served over time: endpoint, changes (newest first, at most 100; truncated when older ones exist), certificates (fingerprint → subject, issuer, expiry for those still in the inventory); 404 for an endpoint outside the caller's discovery sources |
| GET | /projects/{projectId}/discovery/servers | viewer | Servers: each address:port once — host, port, name_count (distinct SNI names), cert_count (distinct certificates served now), source_ids, default_fingerprint / default_subject / default_not_after (the certificate served without a name, else the first answering name's), min_tls_version, kex_worst, managed, unmanaged, failed (every row failed), edge_roles, last_seen_at; plus total, page, page_size, source_names. Parameters: page, page_size (≤100), search (address or any SNI name, case-insensitive; a matching server keeps its whole counts), sort_by host | port | names | last_seen_at, sort_desc, source (comma list / repeated, ≤100 — only those sources' rows), status managed | unmanaged | failed, include_failed=true (servers where every scan failed are hidden otherwise), tls_below_13=true, kex_pqc (as on /discovery/endpoints, matched against the server's weakest served row — its kex_worst), fingerprint (64 hex: servers serving it now), min_tls 1.0 | 1.1 | 1.2 | 1.3 | unknown (the server's lowest TLS version at a successful scan; 400 with status=failed), subnet (a /24 IPv4 or /64 IPv6 network), domain (servers answering a name of that registrable domain or serving a certificate naming it). An unknown value is 400; limited to the caller's discovery sources |
| GET | /projects/{projectId}/discovery/servers/detail?host=&port= | viewer | one server: host, port, rows (every visible source × name row with source_name; a failing row carries failing_since, when its current streak of failed scans began; at most 2000, truncated), certificates (fingerprint → certificate, including those its history names), sources (id → name), findings (open / acknowledged, ≤500), changes (newest first, ≤100, changes_truncated). Query parameters because an IPv6 address holds colons (brackets allowed); 400 bad host or port; 404 when no row is visible to the caller |
| GET | /projects/{projectId}/discovery/tag-rules | viewer | Tag rules in run order (rules, each with matched_count / matched_at from the last apply) and fields (field → operators) |
| POST | /projects/{projectId}/discovery/tag-rules | admin (whole project — a granted-scope admin gets 403) | create a rule (201): name (≤100, unique per project, case-insensitive), description (≤500), enabled (default true), order, match all | any, conditions (1–10 {field, op, value}), tags, owner (≤255); a tag or an owner is required; ≤100 rules per project; 400 on any invalid value; 30/min per project; audited DISCOVERY_TAG_RULE_CREATED |
| PUT/DELETE | /projects/{projectId}/discovery/tag-rules/{ruleId} | admin (whole project) | replace / delete a rule; 404 unknown; 30/min per project (shared with create); audited DISCOVERY_TAG_RULE_UPDATED / _DELETED; the rules are re-applied in the background |
| POST | /projects/{projectId}/discovery/tag-rules/preview | admin (whole project) | what an unsaved rule (body like a rule; name and tags optional) matches now among the certificates the caller can see: matched, sample (≤20 {fingerprint, subject, issuer, not_after}); stores nothing, not audited; 60/min per project |
| GET | /projects/{projectId}/discovery/views | viewer | the caller's saved views in the project (views); page = certificates | servers | findings narrows them |
| POST | /projects/{projectId}/discovery/views | viewer | save a view (201): page, name (≤60), query (the list's URL query, ≤2000 characters, checked by that list's own filters — 400 on an unknown value), pinned; ≤50 per user per project; 30/min per user; not audited |
| PUT/DELETE | /projects/{projectId}/discovery/views/{viewId} | viewer | change (name, query, pinned; the page stays) / delete one of the caller's views; another user's view is 404; 30/min per user |
| GET/PATCH | /projects/{projectId}/discovery/findings (& /{id}) | viewer (list) / operator (status) | Findings |
| GET | /projects/{projectId}/discovery/findings/summary | viewer | findings counts |
| GET | /projects/{projectId}/discovery/findings/{id}/history | viewer | the finding's history, newest first, at most 200 (truncated): kind created / status (from_status → to_status, by, note) / severity (from_severity → to_severity); 404 for a finding the caller cannot see |
| POST | /projects/{projectId}/discovery/findings/bulk | operator | bulk status change by ids or filter, at most 10,000 — 10/min per project |
| GET | /projects/{projectId}/discovery/target-candidates (& /{candidateId}) | viewer | Target candidates — state open | removed | added |
| POST | /projects/{projectId}/discovery/target-candidates/{candidateId}/remove, /restore | operator | remove a candidate for good / undo it |
| GET | .../discovery/certificates/{fingerprint}/manage | operator | Manage |
| GET | /projects/{projectId}/discovery/summary | viewer | dashboard numbers; total_servers (distinct address:port) beside total_endpoints (rows); managed_count, unmanaged_count and outdated_count (earlier versions of managed certificates still served — in neither of the other two) |
| GET | /projects/{projectId}/discovery/quantum | viewer | quantum readiness: key_exchange (by_class, servers, rows, groups, classical_on_tls12, supported_not_used, by_source — servers = host:port whose last scan served a certificate, each counted once by its weakest row; classes hybrid, pq, classical, none, unknown), certificates (PQC buckets), recent_changes (the 50 newest kex_pqc_lost / kex_pqc_gained rows with their endpoint, null when gone), scanner_offers (quantum-safe groups the scan's main handshake offers), trend (per UTC day of the last 90: servers, by_class, summed over the caller's sources); limited to the caller's discovery sources; 503 DISCOVERY_VISIBILITY_UNAVAILABLE when those cannot be read |
| GET | /projects/{projectId}/discovery/activity | viewer | what changed over the last days (1–90, default 7; 400 otherwise): counts per kind (server_new, server_gone, new_certificate, certificate_replaced, tls_changed, finding_opened, finding_reopened, finding_resolved — findings counted one by one; a reopened or resolved finding counts once per day however often it changed), events newest first (kind, at, host, port, names, name_count, fingerprint, old_fingerprint, changes, details, finding_id, finding_type, severity, title, count, by — findings of one type and severity raised the same day are one event with count; changes of one server on one day are one event listing names), truncated (kinds that reached 500 rows), certificates (fingerprint → subject, issuer, not_after, managed, self_signed), source_names; limited to the caller's discovery sources; 503 DISCOVERY_VISIBILITY_UNAVAILABLE when those cannot be read |
| GET | /projects/{projectId}/discovery/overview | viewer | Overview page: as_of, expiry_weeks (13 × from, to, managed, unmanaged, outdated), expired, expired_unmanaged, expired_unanswered, tls_versions (version, servers — lowest version per server that answered), servers; cached up to 60 s |
| GET | /projects/{projectId}/discovery/sources/health | viewer | the scan health of every source the caller can see (sources) |
| GET | /projects/{projectId}/discovery/insights/issuers | viewer | Insights → Issuers: issuers (≤500, truncated) — issuer (empty for the self_signed group), issuer_dns, issuer_dn_sample, certificates, managed, expiring_30d, expired, servers, trust (public, private, untrusted, not_served), caa (ok, violation, unknown_issuer, error, unchecked) |
| GET | /projects/{projectId}/discovery/insights/domains | viewer | Insights → Domains: by=domain (default) or subnet (400 otherwise); groups (≤2000, truncated) — key, label, groupable, certificates, servers, names, expiring_30d, expired, unmanaged, critical, failed_servers |
| GET | /projects/{projectId}/discovery/insights/teams | viewer | Insights → Teams: tags, owners — value, none (the no-tag / no-owner row), certificates, critical, expiring_30d, expired, unmanaged |
| GET | /projects/{projectId}/discovery/insights/risk | viewer | Insights → Risk: factors (code, label, weight, certificates), by_level, scored, unscored |
| GET | /projects/{projectId}/discovery/insights/reach | viewer | Insights → Reach: rows (fingerprint, servers, names, subject, issuer, not_after, wildcard, managed, outdated, in_inventory), total, page, page_size (≤100; 400 otherwise), filters wildcard, managed. Every insight view: limited to the caller's discovery sources; 503 DISCOVERY_VISIBILITY_UNAVAILABLE when those cannot be read; 422 DISCOVERY_TOO_LARGE past 500,000 certificates or server-certificate pairs |
Project — notifications
| Method | Path | Role | See |
|---|---|---|---|
| GET/POST/PATCH/DELETE | /projects/{projectId}/notification-channels | read: viewer · writes: admin | Channels; a PATCH that keeps a stored password / secret blank while changing where it goes (SMTP host, port, TLS mode or verification off; webhook URL) is 400 CHANNEL_CREDENTIAL_REQUIRED |
| POST | .../notification-channels/{id}/test | admin | delivery probe |
| GET/POST/PATCH/DELETE | /projects/{projectId}/notification-rules | read: viewer · writes: 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 | paginated log lines |
| GET | /projects/{projectId}/jobs/{id}/logs/since | viewer | lines after after_id (limit default 200) — for live tailing |
| POST | /projects/{projectId}/jobs/{id}/retry | admin | retry a failed job; 20 requests/minute; 422 for a ca_place_order job (would place a new paid order — use Reissue) |
| POST | /projects/{projectId}/jobs/{id}/cancel | admin | cancel a pending / in-progress job; 422 for a ca_cleanup_dcv 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 |
| POST | /projects/{projectId}/bulk-actions | operator | Bulk; 10 requests/minute per project |
| GET | /projects/{projectId}/bulk-actions/{bulkId} | viewer | progress of one bulk action (there is no list route) |
| GET | /projects/{projectId}/approval-requests | project admin | Approvals |
| GET | /approval-requests/my, /approval-requests/{id} | any | Approvals |
| POST | /approval-requests/{id}/{approve,reject} | project admin of the request's project, or admin on the request's resource for a user limited to granted resources (approve: never the requester) | Approvals |
| POST | /approval-requests/{id}/{execute,retry} | the requester (still an operator in the project, and on the resource) or a reviewer | Approvals |
| POST | /approval-requests/{id}/cancel | the requester or a reviewer | All five actions: 10 requests/minute per user |
| GET | /downloads/{token} | authenticated — the user the token was minted for, still an operator in the project | Not project-scoped. Redeems the single-use token minted when an approved download request is executed — Download |
Project — access
A user whose project role is limited to granted resources gets 404 for a resource it was not granted and 403 (code: ACCESS_DENIED) for one it sees without the needed role. Lists, counts and dashboards cover only its resources — Resource grants.
| Method | Path | Role | See |
|---|---|---|---|
| GET | /projects/{projectId}/my-access | viewer | the caller's own standing: unrestricted, role, and per type enforced / all / can_create |
| GET | /projects/{projectId}/members | project admin (a restricted admin included) | users and user groups with a role in the project: kind (user or group), user_id or group_id, the effective role and scope (project or granted) |
| GET | /projects/{projectId}/grants/{resourceType}/{resourceId} | admin on the resource | who has a grant on it: {grants: [{user_id or group_id, role}]} |
| PUT | /projects/{projectId}/grants/{resourceType}/{resourceId} | project admin, and admin on the resource | replaces the list; each entry names user_id or group_id; only project members; never above the caller's own role |
| GET/PUT | /projects/{projectId}/users/{userId}/grants | admin of the whole project | one user's grants: {resources: [{resource_type, resource_id, role}], types: [{resource_type, role?, can_create?}]} (PUT replaces them) |
| GET/PUT | /projects/{projectId}/groups/{groupId}/grants | admin of the whole project | one user group's grants, same shape; the group must hold a role in the project |
Governed resources in list and detail responses carry access_role — the caller's role on them — when the caller is limited to granted resources.
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.