# SSL certificates

> The certificate lifecycle from CSR to issuance, the three rules behind most SSL errors, and how to choose a package.

SSL is the most order-sensitive part of the API. Calling these endpoints out of sequence is the commonest source of errors, so this section is laid out **in the order you must call them**.

## The lifecycle

```text
  generate-csr  (optional — or bring your own CSR)
        │
        ▼
   initialize ─────────────► WaitingForInstall      ← you are charged here
        │                          │
        │                          │  7-day configuration window
        ▼                          ▼
    configure ──────────► ConfigurationStarted
        │
        ├──► WaitingForValidation / ConfirmationSent  ← prove domain control
        │                          │
        ▼                          ▼
   check-status (poll) ─────────► Active             ← issued
        │
        ├──► certificate-content   download and install
        ├──► reissue               new key or new approver
        └──► revoke                cancel
```

| Step | Endpoint | Charges? |
| --- | --- | --- |
| 0a | `POST /ssls/generate-csr` — generate a CSR and key | no |
| 0b | `POST /ssls/check-csr` — inspect a CSR you hold | no |
| 0c | `GET /ssls/approvers` — valid approver e-mail addresses | no |
| 1 | `POST /ssls/initialize` — **buy the certificate** | **yes** |
| 2 | `PUT /ssls/configure` — submit CSR, contact, validation method | no |
| 3 | `PUT /ssls/check-status` — poll until issued | no |
| 4 | `GET /ssls/certificate` — full detail | no |
| 5 | `GET /ssls/certificate-content` — download the certificate | no |

## Three rules that will bite you

:::danger[1 · You have 7 days to configure what you buy]
`initialize` takes your money and reserves the certificate. If you do not call `configure` within **7 days**, the certificate is cancelled and `configure` starts failing with `Ssl:10056`. On refundable packages the fee is returned to your balance automatically.

**Never call `initialize` until you have the CSR and contact details ready.** If your checkout collects those after payment, call `initialize` at the end of checkout, not the beginning.
:::

:::caution[2 · The term is always one year]
There is no `period` parameter. Multi-year certificates are not sold — CA industry rules cap certificate lifetime at about 13 months. Do not build a year selector.
:::

:::caution[3 · Renewal opens 30 days before expiry, and there is no renewal endpoint]
Renewing is simply `initialize` + `configure` again for the same domain, within 30 days of expiry. Earlier than that gives `Ssl:10057`. Remaining days are **not** carried over — the new year starts when you configure, so renew close to expiry rather than early.
:::

## Choosing a package

Package metadata comes from `GET /api/v1/products/ssls`. Two things drive the choice.

| Value | Validation | What the CA checks | Typical wait |
| --- | --- | --- | --- |
| 1 | `DV` | Domain control only | 5–30 minutes |
| 2 | `OV` | Organisation documents verified | 1–3 business days |
| 3 | `EV` | Extended legal verification | 3–10 business days |

Package shape decides which `configure` fields are mandatory:

| Package covers | `sanList` | `wildcardList` |
| --- | --- | --- |
| One domain | forbidden | forbidden |
| Multiple domains | **required** | forbidden |
| Wildcard | forbidden | **required** |