npmctl models certificates as owner-scoped resources. Because NPM certificate payloads vary by DNS provider and API version, certificate declarations support an api_payload pass-through merged with name, domain_names, certificate_type, and managed metadata.
Proxy hosts should reference certificates by certificate_ref whenever the certificate is declared in the same desired state.
Certificate reconcile policy is explicit:
--certificate-mode=reusereuses one compatible live certificate for the same provider and normalized domain set and blocks new issuance when none exists.--certificate-mode=createreuses a compatible live certificate when present and otherwise allows creation.--certificate-mode=rotateopts into create-new certificate behavior instead of silently reusing a compatible live certificate.
Issuance safety is local and fail-closed:
- repeated issuance attempts for the same provider and normalized domain set are deduplicated while one is in flight
- failed issuance attempts enter a cooldown window before npmctl will try again
- Certbot lock contention is classified as retryable, while stale
No order for ID ...failures are surfaced as cleanup-required certificate errors