Skip to main content

Revoke a certificate

Revocation tells the Certificate Authority the cert is no longer trusted and should be published in CRL/OCSP as revoked. It is a one-way action — you cannot un-revoke, you can only issue a fresh cert. CertAutoPilot calls the issuer (ACME or MSCA), records the reason, emits the audit + notification events, and marks the cert as revoked.

Not available for imported certificates

Revocation calls the issuing CA. Imported (bring-your-own) certificates have no CA, so Revoke is rejected for them — use Delete to retire an imported certificate. If the external CA that issued it supports revocation, revoke it there.

When to revoke​

  • Key compromise — the private key has been exposed (bucket leak, HSM incident, lost laptop). Use reason keyCompromise. Browsers honour this with CRLSets / OneCRL escalation.
  • Ownership change — the domain is being transferred and the cert should not remain valid with the previous owner.
  • Decommission — the app is going away; you want to make the cert inert in case it leaks.
  • Subject problem — wrong identifiers, wrong organization details. Use cessationOfOperation or affiliationChanged.
  • Superseded — you reissued with different parameters and want the old cert withdrawn.
Revocation is not the same as deletion

The MongoDB record stays (for audit), the cert is marked revoked, and the CA publishes it in CRL/OCSP. Delete it from CertAutoPilot only after the CA's revocation propagation window has passed (typically 24 hours).

Prerequisites​

  • Admin role or higher on the project. Operator is not sufficient — worth knowing before an incident, since revocation is the one action you need under time pressure.
  • An approval workflow may gate revocation; if so, you get a "request approval" dialog instead of direct revoke.
  • For ACME certs the associated account key must still be loaded — it is used to sign the revocation request. Deleting the account before revoking its certs makes revocation impossible from CertAutoPilot.

Revoke​

  1. Go to the certificate detail page.
  2. Click Revoke (top-right actions). An expired certificate can still be revoked — revocation is what tells the CA the key is compromised, which matters regardless of expiry. The button is disabled for a certificate that is already revoked, was imported rather than issued here, came from AD CS (MSCA), or when the approval workflow requires a different role.
  3. Pick a reason:
    • unspecified (0) — default, no strong signal.
    • keyCompromise (1) — strong signal; browsers treat this as severe.
    • affiliationChanged (3) — org restructure.
    • superseded (4) — replaced by a new cert.
    • cessationOfOperation (5) — app/domain shutting down.
    • privilegeWithdrawn (9).
    • Others per RFC 5280.
  4. Optional note — free text stored on the audit record.
  5. Click Confirm. A revoke_certificate job enqueues.

Revocation applies to ACME-issued certificates. Microsoft AD CS (MSCA) and imported certificates cannot be revoked through CertAutoPilot — revoke those at the issuing CA directly.

What happens​

  1. The worker loads the cert + private key + account.
  2. It signs a revocation request against the CA using the ACME account key.
  3. The CA returns success; the cert state flips to revoked.
  4. A cert.revoked event is written to the timeline and notification rules fire.
  5. Active distributions are NOT automatically rolled back. If the cert is live on an HTTPS endpoint, that endpoint still presents it — you must distribute a replacement cert or explicitly rollback the distribution.
Revocation does not remove the cert from your servers

Browsers eventually learn the cert is revoked (via CRL/OCSP) and refuse to trust it, breaking HTTPS. Always issue + distribute a replacement cert BEFORE revoking the old one, unless you are deliberately taking the service down.

Verify​

  • Detail page shows status: revoked and the reason.

  • Timeline has a cert.revoked event with actor, reason, and note.

  • Third-party check (several minutes post-revocation):

    openssl ocsp -issuer chain.pem -cert cert.pem \
      -url $(openssl x509 -in cert.pem -ocsp_uri -noout)

    Expected: Cert Status: revoked.

Troubleshooting​

"account key not loaded"​

The ACME account was deleted from CertAutoPilot before its certs were revoked. Recreate an account on the same CA and attach it to the cert (Settings → ACME accounts → the new one), then try again. Some CAs also accept revocation by presenting the cert's own private key without the account — this path is not currently wired in the UI but is doable via the API.

"already revoked"​

The CA says it is already revoked but CertAutoPilot thinks it is active. Happens if someone revoked via the CA portal directly. There is no Refresh from CA button — an hourly sweep checks certificates against OCSP and then CRL and reconciles the status itself, so leave it and it corrects within the hour.

Revoking one retained version​

Revocation normally applies to the whole certificate. You can instead revoke a single retained historical version by passing its artifact id:

POST /api/v1/projects/{project}/certificates/{id}/revoke
{ "reason": 1, "artifact_id": "<version id>" }   // reason is the NUMERIC RFC 5280 code (1 = keyCompromise); a string is rejected

That version is revoked at the CA and marked revoked in the history, while the certificate itself stays active — useful when an older key leaked but the current one is sound. A revoked version also drops out of rollback eligibility, so nothing can redeploy it. Naming the current version instead falls through to the normal whole-certificate path. There is no button for this yet; it is API-only.

Revocation detected out of band​

An hourly sweep re-checks certificates against the CA (OCSP first, then CRL). If one was revoked outside CertAutoPilot, the status is reconciled automatically and a notification fires. Retained previous versions are checked too, at most every 24 hours each and 20 per certificate per cycle; a previous version found revoked is marked as such and raises a warning without touching the live certificate.

Revoke button is disabled with "requires approval"​

Approval workflow policy is on for this action. Click Request approval instead — an approver with the right role will see it in /my-requests.

See also​