Skip to main content

File-based domain control validation (http-token and http-token-dynamic)

This article describes how the CertCentral Services API handles requests to validate domains submitted with a domain control validation (DCV) method of http-token and  http-token-dynamic.

Note

DigiCert only supports the use of the file-based DCV methods to demonstrate control over fully qualified domain names (FQDNs) exactly as named in the certificate request.

Use one of the other supported DCV methods, such as email, DNS TXT, and CNAME, to:

  • Validate wildcard domains (*.example.com).

  • Include subdomains in the validation when validating a higher-level domain. For example, if you want to cover www.example.com when validating the higher-level domain example.com.

  • Prevalidate entire domains and subdomains.

Certificate order requests

When using the Services API to request DV, OV, and EV TLS/SSL certificates, you can choose file-based DCV by setting the dcv_method request parameter to http-token or http-token-dynamic. Because http-token and http-token-dynamic are not valid DCV methods for wildcard domains, the API handles requests differently when the common_name or dns_names fields include a wildcard domain.

Warning

DV TLS certificates only support the http-token DCV method. They do not support the http-token-dynamic DCV method.

Non-wildcard domains only

Certificate order requests with common_name and dns_names fields that only contain non-wildcard domains are accepted. To complete domain validation, upload the random value in the API response to each individual FQDN on the order.

  • http-token

    To complete domain validation, upload the random value in the API response to each individual FQDN on the order.

    For example, to validate the domains in the JSON payload below, upload the random value to example.com and sub.example.com.

    Example request with non-wildcard domains

    {
    "certificate": {
        "common_name": "example.com",
        "dns_names": [
          "sub.example.com"
        ]
        ...
    },
    "dcv_method": "http-token",
    ...
}

  • http-token-dynamic

    To complete domain validation, add a file with a random file name that contains a random value in the API response to each individual FQDN on the order.

    For example, to validate the domains in the JSON payload below, add a file with a random file name that contains a random value to example.com and sub.example.com.

    Example request with non-wildcard domains

    {
    "certificate": {
        "common_name": "example.com",
        "dns_names": [
          "sub.example.com"
        ]
        ...
    },
    "dcv_method": "http-token-dynamic",
    ...
}

Wildcard domains only

For products that allow wildcard domain names, certificate order requests with common_name and dns_name fields containing wildcard domains only (*.example.com) are rejected with the error code invalid_wildcard_dcv_method. To request a certificate that only includes wildcard domains, use a different DCV method (email, dns-txt-token, or dns-cname-token).

Example http-token-dynamic request with wildcard domain

{
    "certificate": {
        "common_name": "*.example.com",
        ...
    },
    "dcv_method": "http-token-dynamic",
    ...
}

Both wildcard and non-wildcard domains

For products that allow wildcard domain names, certificate order requests with common_name and dns_name fields that contain a combination of wildcard and non-wildcard domains (for example, *.example.com, my.biz.example.com, and example.net) are handled differently depending on whether the order is for a DV or OV/EV certificate.

Note

EV certificates only allow wildcard domains if the right-most domain label is "onion" (*.example.onion). To learn more about ordering a certificate for your .onion address, visit Ordering a .onion certificate from DigiCert.

Example http-token request with wildcard and non-wildcard domains

{
    "certificate": {
        "common_name": "*example.com",
        "dns_names": [
          "my.biz.example.com"
          "example.net"
        ]
        ...
    },
    "dcv_method": "http-token",
    ...
}

DV certificate orders

DV certificate order requests with common_name and dns_name fields containing a combination of wildcard and non-wildcard domains are rejected with the error code invalid_wildcard_dcv_method. To request a DV certificate that includes wildcard and non-wildcard domains, use a different DCV method (email, dns-txt-token, or dns-cname-token).

OV/EV certificate orders

OV/EV certificate order requests with common_name and dns_name fields that contain a combination of wildcard and non-wildcard domains are accepted.

  • Non-wildcard domains (example.net) are submitted for validation with a DCV method of http-token or http-token-dynamic.1 To complete DCV checks, upload the token in the API response for each of these domains.

  • Wildcard domains (*.example.com) are submitted for validation with a DCV method of email. If the order includes non-wildcard subdomains of the wildcard domain (my.biz.example.com), these subdomains are validated when you complete the email DCV check for the wildcard domain. These subdomains are not individually submitted for file-based DCV.

Note

1For accounts configured to submit base domains for validation

If you request an OV/EV certificate for both a wildcard domain (*.sub.example.com) and a higher-level domain of the wildcard domain (example.com), the shared base domain (example.com) is submitted for validation using email DCV. The DCV method for the base domain is automatically changed to email when you submit your request. This allows DigiCert to honor the account setting to submit the base domain for validation. To validate both domains, complete the email DCV check for the base domain.

Domain prevalidation

The Services API allows you to prevalidate domains for OV and EV certificate requests. Prevalidating domains reduces the number of tasks you must complete before your OV or EV certificate can be issued.

Use these endpoints to submit domains for prevalidation:

When you submit a domain for prevalidation, you choose which DCV method to use to prove control over the domain.

  • Using email, dns-txt-token, or dns-cname-token (recommended) validates the submitted domain and any wildcard domains or subdomains of the submitted domain.

  • Using http-token or http-token-dynamic only validates the specific FQDN submitted for prevalidation.

Note

Requests to add or submit a wildcard domain  (*.example.com) for validation using the http-token or http-token-dynamic DCV methods are rejected with the error code invalid_wildcard_dcv_method.

In this section: