# Certificates

> How each domain gets and keeps its HTTPS certificate.

Source: https://docs.customdomain.ai/docs/connect-flow/certificates

The edge issues a certificate for a domain the first time someone visits it
over HTTPS once the domain points at CustomDomain™ (Let's Encrypt, through the
domain itself). Renewal starts about 30 days before expiry and needs no access
to your DNS, so it works the same whatever access was kept. A failing renewal is
retried after 30 minutes at first, then less often after each failure, up to
about once a day, while the current certificate keeps serving.

## Read a domain's certificate

`GET /v1/connections/{id}/certificate` returns what the edge last reported:

```json
{
  "certificate": {
    "host": "shop.acme.com",
    "status": "issued",
    "issuer": "R11",
    "issued_at": "2026-09-01T12:00:00Z",
    "renewed_at": "2026-10-01T12:00:00Z",
    "expires_at": "2026-12-30T12:00:00Z",
    "days_left": 92,
    "next_renewal_at": "2026-11-30T12:00:00Z",
    "managed": true
  },
  "renewal": { "automatic": true, "needs_dns_access": false, "retry_every": "30 minutes at first, then less often after each failure, up to about once a day" },
  "history": [ { "kind": "certificate.renewed", "created_at": "2026-10-01T12:00:00Z" } ]
}
```

`status` is `issued`, `renewing` (renewal keeps failing while the current
certificate still serves; `last_error` says why), `failed`, `pending`,
`revoked` or `not_reported` (the edge has not reported one yet). A failing
certificate also carries `last_error`, `failing_since` and `failure_count`.
`attention` is set when a person should look: `failed`, `renewal_failing` (a
renewal is failing while the old certificate serves), `expiring` (14 days or
less without a renewal) or `expired`. An apex that redirects www also returns
`www_certificate`. Every plan can read this endpoint.

## Alerts

* **Webhooks**: `certificate.issued`, `certificate.renewed`,
  `certificate.failed` (once per failure episode) and `certificate.expiring`
  (14, 7 and 3 days before an unrenewed certificate expires, and when it did).
  Each carries a `certificate` object. See the
  [event catalog](/docs/webhooks/overview#event-catalog). A certificate an
  edge finds in its cache after a restart is recorded without an event, so
  restarts send nothing. The older `secure_status` webhook is sent only where
  the deployment has Secure on (`SECURE_ENABLED`), once per status change.
* **Email**: the workspace's owners and admins get one email per threshold
  (14, 7 and 3 days, expired, and failed). A renewal that is still failing
  after 6 hours gets a `renewal_failing` email.
* **Console**: the domain page's Certificate tab shows the state, the dates,
  the last error and the history, and the page itself shows a banner that links
  there when it needs attention.

When a domain is removed, its certificate stops renewing and is deleted from
every edge within a minute.
