Skip to main content
Video tutorial · 1:32

Download a certificate

For operators who need to export a cert manually — emergency deployments, debugging, audit snapshots. A direct download returns the material straight from the API; an approval-gated download is redeemed once through a single-use token with a short expiry. Every download is recorded in the audit log (CERTIFICATE_DOWNLOADED) with the actor and the selected format.

Supported formats​

The format field accepts ten values. The response is JSON: the public PEM fields (cert_pem, chain_pem, fullchain_pem) are always present, and the binary formats add base64 fields on top. The UI turns the response into the file(s) below.

private_key is returned only when the requested format actually needs it — pem (the default when format is omitted), key, bundle and all. It is not returned for cert, chain and fullchain (public material only), nor for pfx, jks and der, whose containers already carry the key in their own encoding. A download therefore never hands out key material the caller did not ask for.

FormatContentsTypical use
pemThe PEM fields only. The API default when format is omitted.Scripted access that parses the JSON itself.
certLeaf certificate (.crt)Nginx ssl_certificate when the chain is separate.
chainIntermediate(s) only (.pem)Servers that want cert + chain in separate files.
fullchainLeaf + intermediates (.pem)Most nginx / Apache configs (ssl_certificate).
keyPrivate key (PKCS#8 PEM, .key)Web server config.
bundleFullchain + private key in one .pemHAProxy and anything else that wants a single file.
pfxPKCS#12 — leaf + key + chain, password-protected (.pfx)Windows / IIS import. A password may be supplied; when omitted, one is generated and returned. Encrypted with AES-256 unless pfx_encryption is legacy (see below).
derBinary DER certificate (.der) plus a PKCS#8 DER key (.key.der) — two filesAppliances and Java tooling that reject PEM.
jksJava KeyStore (.jks), password + entry aliasJava application servers. Password and alias may be supplied; when omitted, a password is generated and the alias defaults to the primary domain.
allA zip of cert, chain, fullchain, and keyOne-click snapshot for manual handoff.

password is accepted only for pfx and jks; alias only for jks; pfx_encryption only for pfx. Any other combination is rejected with 400.

PFX encryption​

pfx_encryption chooses how the .pfx is encrypted:

ValueEncryptionUse it for
modern (default)AES-256, PBKDF2-HMAC-SHA256, HMAC-SHA256Windows Server 2019 and later, Windows 10 1709 and later, macOS, Java, OpenSSL
legacyTripleDES-SHA1, MAC SHA-1Windows Server 2016 and Windows 10 before 1709, which cannot open an AES file and answer "The specified network password is not correct."

Legacy is weaker: TripleDES with SHA-1 makes guessing the password cheaper. Use it only for those hosts, with a long random password (or the generated one). In the UI the PFX dialog has a PFX encryption field. A download that needs approval stores the choice with the request, and the approved download uses it.

Steps​

  1. Open the certificate detail page.
  2. Click Download (top-right actions) and pick a format from the menu.
  3. For PFX and JKS a small modal collects an optional password (and, for JKS, an entry alias). Leave them empty to have CertAutoPilot generate a password — it is shown once after the download.
  4. The file downloads straight from the API response. der produces two files; all produces a zip.
Approval-gated downloads use a single-use token

When the project's approval policy gates downloads for you, the direct call returns an approval request instead of the material. Executing the approved request (POST /approval-requests/{id}/execute) returns a download_token in its response body; that token is redeemed once at GET /downloads/{token} and is invalidated on use. It is valid for 60 seconds, so a leaked URL stops working almost immediately — a re-download needs a fresh approval execution.

Version history & downloading a past version​

Every renewal keeps the previous certificate and its private key as a historical version — nothing is overwritten. The certificate detail page's Certificates tab lists every version with its serial number, expiry, and issue date; each row has its own Download button, so you can export any past version (cert, chain, key, or a zip) — the matching key for that version is served automatically.

Retention is bounded by History Versions in the Certificate Defaults card of Settings → General (API field cert_history_max_versions; default 10 versions per certificate, -1 = keep everything). Pruning runs at every artifact write — issuance, renewal, and certificate import alike, not only at renewal. When a new version pushes the count over the limit, the oldest versions — and any private key no longer referenced by a retained version — are pruned automatically. A private key shared across several retained versions is never dropped while any of them still needs it.

Pruning also pins any version a distribution still references (deployed, rolled back to, or awaiting a queued rollback): a pinned version is never pruned, even when it falls past the retention count. See retention pinning.

Via API, add artifact_id (from artifact_history[].id on the certificate detail response) to the download body to fetch a specific version:

curl -X POST -H "Authorization: Bearer <access_token>" \
https://cap.example.com/api/v1/projects/$PID/certificates/$CID/download \
-d '{"format":"fullchain","artifact_id":"<version-id>"}'
Approval-gated downloads are current-version only

When the project's approval policy gates downloads for you, an approved download always returns the current version. Per-version download is available on the direct path — for admin/owner users, or for operators the policy does not gate for downloads.

Permissions​

  • Operator role or higher is required to download.
  • There is no separate key-export permission. Any role that can download can download the private key, in every format that carries one (key.pem, PKCS#12, bundle). If you need to restrict this, restrict the role.
  • When the project's approval policy (Settings → Approvals) gates downloads for an operator, a download approval request is created instead — see Approval workflow.

Audit trail​

Every download writes:

  • An audit_logs entry: actor (user), format, whether the payload carries the private key (includes_private_key — true for pem, key, bundle, all, pfx, jks and der), IP address, timestamp.
  • For an approval-gated download, a record in the download_tokens collection. It is not a long-lived forensic record: a MongoDB TTL index on expires_at reaps each row about a minute after it expires. Use the audit log and the certificate timeline for retrospective analysis.

API access​

There is one download endpoint, and it returns the payload directly — nothing is minted first:

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
https://cap.example.com/api/v1/projects/$PID/certificates/$CID/download \
-d '{"format":"fullchain"}'
# → {"cert_pem":"...","chain_pem":"...","fullchain_pem":"...","private_key":"..."}

Binary formats add base64 fields and, where applicable, the generated password:

curl -X POST -H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
https://cap.example.com/api/v1/projects/$PID/certificates/$CID/download \
-d '{"format":"pfx","password":""}'
# → {..., "pfx_base64":"MIIK...", "pfx_password":"a3f9..."}

The separate token route exists only for approval-gated downloads. When approval is required, the call above returns an approval request; after the request is approved, executing it hands back a single-use token:

# Execute the approved request — the response carries the token
curl -X POST -H "Authorization: Bearer <access_token>" \
https://cap.example.com/api/v1/approval-requests/$RID/execute
# → {"download_token":"...", ...}

# Redeem it once, within 60 seconds
curl -H "Authorization: Bearer <access_token>" \
https://cap.example.com/api/v1/downloads/$TOKEN

The token route serves the current version in the format the request was made with — the same JSON as a direct download of that format, plus a format field naming it. The request keeps the format (and a JKS alias, and a PFX's pfx_encryption) but never a password: a PFX or JKS comes back sealed under a generated password, returned with it. A request filed before the format was kept returns every PEM part (format: "all").

See API reference for full schema.

Troubleshooting​

403 on a download​

The role is below Operator on that project. There is no key-export policy toggle to check — if downloads are gated, it is the Download rule of the project's approval policy (Settings → Approvals), which returns a pending approval request rather than a 403.

"token not found or expired"​

Approval download tokens live 60 seconds and are single-use. Re-execute the approved request to get a fresh one; if the approval request itself has already been consumed, submit a new download request.

PKCS#12 bundle won't import​

The pfx format is always password-protected — use the password returned in pfx_password (shown once in the UI after the download). "The specified network password is not correct." on Windows Server 2016 (or Windows 10 before 1709) with the right password means the host cannot read AES: download again with PFX encryption: Legacy ("pfx_encryption": "legacy"). For another importer that rejects both, export cert + key (or der) and build the keystore locally.

See also​

Video tutorial

Short, hands-on videos showing this feature working for real. English audio, English and Turkish subtitles. All video tutorials →

Download a Certificate as PEM, PFX, DER or JKSYouTube ↗