Where does CertMate store certificates, and how do I retrieve them programmatically?

[fabriziosalmi]

I issued a cert and now I need to consume it from another service — copy it to an nginx host, push it to AWS ACM, attach it to a load balancer, etc. Where does CertMate actually keep the cert files, and what is the canonical way to fetch them from a script?

[fabriziosalmi]

Three answers depending on which storage backend you configured. Local filesystem is the default; the four cloud backends only kick in if you opted into them in Settings → Storage Backend.

Default — local filesystem. Certificates live under data/certs/<domain>/:

data/certs/example.com/
├── cert.pem        # the leaf certificate
├── chain.pem       # the issuer chain
├── fullchain.pem   # cert.pem + chain.pem concatenated
└── privkey.pem     # the private key (mode 0600)

If you mounted ./data:/app/data (Q2) you can read these files directly from the host — but the durable contract is the API, not the file layout.

API — single file. Each file is a separate endpoint, so you can pipe one specific artifact into a downstream system without parsing JSON:

TOKEN=$(grep CERTMATE_TOKEN .env | cut -d= -f2)
HOST=http://localhost:8000

curl -fsSL -H "Authorization: Bearer $TOKEN" \
  "$HOST/api/certificates/example.com/download/fullchain" \
  -o /etc/nginx/ssl/example.com.fullchain.pem

curl -fsSL -H "Authorization: Bearer $TOKEN" \
  "$HOST/api/certificates/example.com/download/privkey" \
  -o /etc/nginx/ssl/example.com.privkey.pem
chmod 0600 /etc/nginx/ssl/example.com.privkey.pem

Available endpoints: cert, chain, fullchain, privkey. The response Content-Type is application/x-pem-file.

API — JSON bundle. PR #128 added a ?format=json variant for automation that wants every artifact in one request without four separate curl calls:

curl -fsSL -H "Authorization: Bearer $TOKEN" \
  "$HOST/api/certificates/example.com/download?format=json"

Returns:

{
  "domain": "example.com",
  "cert": "-----BEGIN CERTIFICATE-----\n…",
  "chain": "-----BEGIN CERTIFICATE-----\n…",
  "fullchain": "-----BEGIN CERTIFICATE-----\n…",
  "privkey": "-----BEGIN PRIVATE KEY-----\n…",
  "not_after": "2026-08-14T12:00:00Z",
  "ca": "letsencrypt"
}

Useful when the consumer is a templating engine (Ansible, Helm) that wants a single fact-block, not four files.

Cloud storage backends. If you switched to Azure Key Vault, AWS Secrets Manager, HashiCorp Vault, or Infisical (Settings → Storage Backend), the PEM files are written to that backend instead of to data/certs/. The API download endpoints above still work — CertMate fetches from the backend on demand and serves the same PEM bytes back. From the caller's point of view nothing changes. Native object support (Azure Key Vault Certificate-object mode, PR #118) stores the cert as a managed object in addition to the secret, which is what AKS / Key Vault Reference syntax expects.

Deploy hooks — the push model. If the consumer is on the same host as CertMate, the cleaner pattern is to skip the pull entirely and use a deploy hook (Q5). The hook fires on issuance / renewal with $CERTMATE_CERT_PATH, $CERTMATE_KEY_PATH, $CERTMATE_FULLCHAIN_PATH exported. Copy the file, signal the service, done. No polling.

Programmatic listing. /api/certificates returns the full list with metadata (domain, not_after, ca, dns_provider, auto_renew). Combine with jq for shell loops that operate on every cert at once.