SSL certificates

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

  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

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.

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.

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