Skip to content

Configure a certificate

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
certificateId required The certificate to configure, from initialize or renew. It must be awaiting configuration.
csr required PEM CSR. Its common name must match the certificate’s domain — the domainName you bought it for.
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

{
"certificateId": "5e8c2a71-4b93-4f06-ae25-1d7f9c3b8042",
"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

{
"certificateId": "5e8c2a71-4b93-4f06-ae25-1d7f9c3b8042",
"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

{
"certificateId": "5e8c2a71-4b93-4f06-ae25-1d7f9c3b8042",
"csr": "-----BEGIN CERTIFICATE REQUEST-----\n...\n-----END CERTIFICATE REQUEST-----",
"approverMail": "admin@apiname.com",
"authenticationType": "Cname",
"webServerType": "Apache",
"wildcardList": "*.apiname.com",
"contact": { "...": "as above" }
}
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
}

For a few packages the installation is done by our technical team instead of the CA’s automated flow — the initialize response says so. Configure them exactly as above. The details are validated the same way, but no order is opened with the CA from this call: the details go to our team, an installation request is opened for you automatically, and the response says so:

{
"success": true,
"message": "SSL configuration received. The installation will be performed by our technical team; an installation ticket has been created for you.",
"certificateId": "5e8c2a71-4b93-4f06-ae25-1d7f9c3b8042",
"status": "InstallationInProgress",
"dcvDetails": null,
"csr": null,
"privateKey": null
}

status stays InstallationInProgress until our team completes the installation. Poll check-status at a slow pace — hourly is plenty — and do not call configure again: a second call gives Ssl:10080.

Errors

Code Meaning and fix
Ssl:10026 Unknown certificateId, or it is not yours. Use the id initialize or renew returned.
Ssl:10056 The 15-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:10080 Team-installed package: your configuration details have already been received and our team is installing it. Do not retry; poll check-status.
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 the certificate’s domain. 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.