# Configure a certificate

> Submit the CSR, contact and validation method that open the order with the certificate authority.

## 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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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](https://www.domainnameapi.com/docs/dns-records/) 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**

```json
{
  "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
}
```

:::caution[`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.
:::

:::tip[What to do next, by validation method]
- **Email** — tell the customer to check `approverMail` and click the link. Then poll `check-status`.
- **Cname** — publish the record from `dcvDetails`. If the DNS is with us, do it with `POST /api/v1/domains/zones`. Then poll.
- **Http / File** — place the file on the web server as the CA specified. Then poll.

If `status` comes back `Active` immediately, a DV certificate was issued instantly and you can go straight to downloading it.
:::

**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. |