DV certificate immediate issuance

When using the API to order your DV certificates, too often time is spent just waiting for the certificate to be issued. By following the steps in this workflow guide, you'll be able to take advantage of our DV certificate immediate issuance feature, allowing you to get your DV certificate issued immediately and reduce your API calls by up to 70%.

To request Encryption Everywhere DV certificates, you must follow these steps and configure an AuthKey for your account. If you do not, you will receive an auth_key_not_setup error when submitting a request.

Overview

In order to take advantage of immediate issuance, you must complete these steps before submitting your DV certificate order:

  1. Create an AuthKey for your CertCentral account.
  2. Generate a certificate signing request (CSR) for the DV certificate order.
  3. Create a timestamp to determine request token validity period.
  4. Construct a request token using your AuthKey and CSR.
  5. Add generated request token to the domain to be secured by the DV certificate.
  6. Submit your DV certificate order.

If all these steps are complete when you submit your DV certificate order, we immediately issue your DV certificate and return it in the response body. If any of these steps are skipped, immediate issuance cannot happen.

Step 1: Create an AuthKey

First, you need to create an AuthKey for your CertCentral account. You will use this key to generate a request token for proving control over the domain. You can create an AuthKey with a POST to the Create AuthKey endpoint.

A successful POST to this endpoint returns a 200 OK HTTP response. The response body includes two key pieces of information:

  • auth_key_id – Unique ID of the created AuthKey.
  • auth_key – Generated AuthKey for your CertCentral account.

Only one AuthKey can exist for your CertCentral account. If your account already has an AuthKey, the Create AuthKey endpoint returns a 400 Bad Request HTTP response with the auth_key_exists_for_account error. If you encounter this error, you can use the AuthKey details endpoint to get your existing AuthKey.

cURL
curl -X POST \
  https://www.digicert.com/services/v2/account/auth-key \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "auth_key_id": "{{auth_key_id}}",
  "auth_key": "{{auth_key}}"
}
400 Bad Request
{
  "errors": [
    {
      "code": "auth_key_exists_for_account",
      "message": "An error occurred while processing your request."
    }
  ]
}

Step 2: Generate a certificate signing request (CSR)

Once you have the AuthKey for your account, the next step is to create a CSR for the certificate order. You'll need the CSR to generate a request token. Make sure to generate your CSR on the server where the certificate will be installed.

Need help creating a CSR? See Create a CSR (Certificate Signing Request).

Step 3: Create a timestamp

The timestamp determines when the 30-day validity period of the request token starts. When creating a timestamp, make sure the resulting validity window coincides with when you will submit your DV certificate order. If your order is submitted before or after the validity window, immediate issuance cannot happen.

You can create a timestamp for a future date. However, do not submit the DV certificate order before that date. Because the request token is not yet "valid", it cannot be used to validate the domain.

After determining when the request token's validity window should start, you need to format the timestamp as shown below:

generic
yyyyMMddhhmmss

For example, October 21, 2019 1:30:12 PM would become 20191021133012.

Step 4: Generate a request token

Request tokens have a 30-day validity determined by the data in the timestamp. When generating a request token, make sure your 30-day timestamp window coincides with when you will submit your certificate order.

Now that you have your AuthKey, CSR, and timestamp, you're ready to generate a request token used to prove control over the domain. This request token allows you to set up your domain's DNS TXT record or fileauth.txt file before placing a certificate order.

How to generate your request token

  1. Construct the secret to be hashed by prepending the timestamp to your PEM-formatted CSR.
  2. Hash the secret using HMAC-SHA256 with your AuthKey as the key.
  3. Convert the resulting hexadecimal hash to a decimal (base10) hash value.
  4. Convert the decimal hash value to a base36 hash value.
  5. Make sure the base36 hash value is at least 50 characters long. If not, prepend with zeros (0) until it is 50 characters long.
  6. Construct the final request token by prepending the timestamp to the base36 hash value.

This example pseudo-code shows how to use the above steps to generate a request token:

generic
# Declare AuthKey, CSR, and timestamp
auth_key = 'certcentral_account_auth_key'
csr = 'pem_formatted_csr'
timestamp = 'yyyyMMddhhmmss'

# Construct secret to be hashed
secret = timestamp + csr

# Hash secret using HMAC-SHA256 and auth_key
hash = hmac.sha256(secret, auth_key)

# Convert hexadecimal hash to decimal
decimal_hash = convertToBase10(hash)

# Convert decimal_hash to base36
base36_hash = convertToBase36(decimal_hash)

# If base36_hash length is < 50, prepend with zeros
valid_hash = base36_hash.padStart(50, '0')

# Construct final request token
request_token = timestamp + valid_hash

Step 5: Place request token

For DV certificate immediate issuance, you must place the request token in one of these places before you order the certificate:

  • In the domain’s DNS as a TXT record.
  • In a fileauth.txt file at a predetermined location on your website.

Once the request token is placed, you can submit your DV certificate order.

DNS TXT

You can demonstrate control over a domain on your DV certificate order by creating a DNS TXT record containing the request token. Once the DNS TXT record is created, you can request your DV certificate.

Be sure to set the dcv_method value to dns-txt-token when using DNS TXT for your request token.

  1. Go to your DNS provider's site and create a new TXT record.

  2. In the TXT Value field, paste the request token.

  3. Depending on your certificate order and domain to be secured, do one of these for the Host field:

    • Base domain (e.g., example.com)
      Leave blank or enter @ symbol (depending on your DNS requirements).
    • Subdomain
      Enter the subdomain to be secured by the certificate.
    • Authorization Domain Name
      Enter _dnsauth.
  4. In the record type field (or equivalent), select TXT.

  5. Select a Time-to-Live (TTL) value or use your DNS provider's default value.

  6. Save the record.

  7. Submit your DV certificate order, making sure to set the dcv_method to dns-txt-token.

File Auth

You can demonstrate control over a domain on your DV certificate order by hosting a fileauth.txt file containing the request token at a predetermined location on your website. Make sure to avoid some of the more common mistakes when using File Auth.

Once the file is available on your website, you can request your DV certificate.

Be sure to set the dcv_method value to http-token when using File Auth for your request token.

  1. Open a text editor (such as Notepad) and paste in the request token.

  2. Save the file as fileauth.txt.

  3. Make the file available on your website at this location (create directories as needed):

    http://[domain.name]/.well-known/pki-validation/fileauth.txt

On Windows-based servers, the .well-known folder must be created via command line: mkdir .well-known

  1. Submit your DV certificate order, making sure to set the dcv_method to http-token.

Step 6: Submit DV certificate order

Once you've placed the request token, you're ready to submit your DV certificate order request. This is done with a POST to the Order DV SSL endpoint.

A successful POST to this endpoint returns a 201 Created HTTP response code. If all immediate issuance requirements are met, the full certificate chain is returned in the response body.

When placing your DV certificate order, make sure the dcv_method value corresponds with the location of the request token.

If any of the prerequisites are missing, immediate issuance won't happen. Instead of receiving the full certificate chain, you'll receive the standard Order DV SSL response body.

cURL (DNS TXT)
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }
    },
    "validity_years": 1,
    "dcv_method": "dns-txt-token"
}'
cURL (File Auth)
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }
    },
    "validity_years": 1,
    "dcv_method": "http-token"
}'
201 Created
{
  "id": 112339,
  "certificate_id": 132345,
  "certificate_chain": [
    {
      "subject_common_name": "example.com",
      "pem": "<pem_certificate>"
    },
    {
      "subject_common_name": "DigiCert SHA2 Secure Server CA",
      "pem": "<pem_certificate>"
    },
    {
      "subject_common_name": "DigiCert Global Root CA",
      "pem": "<pem_certificate>"
    }
  ]
}