Configure a certificate

View as Markdown Open in Claude Open in ChatGPT

PUT `/api/v1/ssls/configure`

Submits everything the CA needs and opens the order at the provider. The CSR, contact and validation method are fixed at this point.

Request

Field	Required	Notes
`domainName`	required	Must have a certificate awaiting configuration.
`csr`	required	PEM CSR. Its common name must match `domainName`.
`privateKey`	optional	Send it only if you want us to store it. Omit to keep it solely on your side.
`approverMail`	required	For `Email` validation, must be one of the `/approvers` addresses.
`authenticationType`	required	`Email`, `Cname`, `Http` or `File`.
`webServerType`	required	`Apache`, `IIS`, `AOL` or `C2Net`.
`sanList`	conditional	Comma-separated extra names. Required for multi-domain packages, forbidden on others.
`wildcardList`	conditional	Comma-separated wildcard names. Required for wildcard packages, forbidden on others.
`contact`	required	One contact, submitted to the CA as both administrative and technical.

A standard single-domain certificate with DNS validation

{
  "domainName": "apiname.com",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzEL...\n-----END CERTIFICATE REQUEST-----",
  "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhki...\n-----END PRIVATE KEY-----",
  "approverMail": "admin@apiname.com",
  "authenticationType": "Cname",
  "webServerType": "Apache",
  "contact": {
    "firstName": "Ahmet",
    "lastName": "Yilmaz",
    "companyName": "Apiname Ltd",
    "eMail": "ahmet@apiname.com",
    "address": "Ataturk Caddesi No 12 Kat 3",
    "city": "Istanbul",
    "state": "Istanbul",
    "postalCode": "34100",
    "country": "TR",
    "phoneCountryCode": "90",
    "phone": "5321234567"
  }
}

A multi-domain certificate

{
  "domainName": "apiname.com",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
  "approverMail": "admin@apiname.com",
  "authenticationType": "Email",
  "webServerType": "Apache",
  "sanList": "www.apiname.com,mail.apiname.com,shop.apiname.com",
  "contact": { "...": "as above" }
}

A wildcard certificate

{
  "domainName": "apiname.com",
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
  "approverMail": "admin@apiname.com",
  "authenticationType": "Cname",
  "webServerType": "Apache",
  "wildcardList": "*.apiname.com",
  "contact": { "...": "as above" }
}

Choosing a validation method

Value	How the customer proves control	When to use it
`Email`	The CA e-mails `approverMail` with an approval link.	Fastest when the customer has one of the standard mailboxes. No DNS or server access needed.
`Cname`	Publish a CNAME record the CA specifies. The values come back in `dcvDetails`.	Best for automation. No mailbox needed, and if the domain’s DNS is with us you can publish the record through the zones API in the same workflow.
`Http`	Serve a file at a URL the CA specifies.	When the customer controls the web server but not DNS or mail.
`File`	File-based variant; the exact path depends on the brand.	Rarely needed.

webServerType determines the bundle format the CA prepares. Pick Apache for Apache, nginx, HAProxy and most Linux stacks; IIS for Microsoft IIS. AOL and C2Net are legacy.

Response — 200

{
  "success": true,
  "message": "SSL certificate configured successfully. Pending domain validation.",
  "certificateId": "5e8c2a71-4b93-4f06-ae25-1d7f9c3b8042",
  "status": "WaitingForValidation",
  "dcvDetails": "{\"MD5\":\"A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6\",\"SHA1\":\"1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0B\",\"UniqueValue\":\"9f3c1a2b8e4d\"}",
  "csr": null,
  "privateKey": null
}

dcvDetails is a JSON string, not an object

Parse it, then read the keys for your CA brand:

Brand	Keys
Comodo / Sectigo	`MD5`, `SHA1`, `UniqueValue`
DigiCert	`DCVRandomValue`
GlobalSign	`DNSText`, `URLMetaTag`

It is empty for Email validation. Use the exact values the CA returned — do not construct the record from memory or a blog post.

Errors

Code	Meaning and fix
`Ssl:10026`	No certificate for this domain. Call `initialize` first.
`Ssl:10056`	The 7-day window expired. The fee is being refunded. Buy a new certificate.
`Ssl:10077`	Same situation, refund already in progress.
`Ssl:10053`	Configuration has already been started — a duplicate or concurrent call. Do not retry; poll `check-status`.
`Ssl:10054`	The provider call timed out and we could not verify the outcome. Do not retry. Open a support ticket with the `certificateId`.
`Ssl:10070`	This package is installed by our technical team. Open a support ticket.
`Ssl:10027 / Ssl:10041`	The certificate’s status does not allow configuring — already configured, cancelled, or already active.
`Ssl:10004`	The CSR could not be decoded.
`Ssl:10040`	Common mistake. The CSR’s common name does not match `domainName`. Check with `check-csr`.
`Ssl:10019`	Wildcard package, but the CSR’s name does not start with `*.`
`Ssl:10035 / Ssl:10030`	`authenticationType` is not a valid value, or not valid for this package.
`Ssl:10051`	That validation method is not supported by this CA brand. Pick another.
`Ssl:10037`	`webServerType` is not a valid value.
`Ssl:10014 / Ssl:10038`	`approverMail` is malformed, or not on the approver list.
`Ssl:10015 / Ssl:10023`	`sanList` sent to a single-domain package, or missing on a multi-domain package.
`Ssl:10020 / Ssl:10021 / Ssl:10032`	Too many SANs (limit 255), duplicates in the list, or an invalid SAN name.
`Ssl:10016 / Ssl:10022 / Ssl:10024`	`wildcardList` sent to a non-wildcard package, or missing on a wildcard package.
`Ssl:10017`	A wildcard entry duplicates the certificate’s main name.
`Ssl:10018`	A wildcard name is invalid. The `*` may only be the leftmost label.
`Ssl:10010 / Ssl:10011 / Ssl:10012`	The `contact` object is missing or incomplete.
`Ssl:10050`	The CA rejected the request. Their explanation is in the message.
`Ssl:10049`	The CA could not be reached. Retry in a few minutes.

Configure a certificate

PUT /api/v1/ssls/configure

Choosing a validation method

PUT `/api/v1/ssls/configure`