Skip to main content

DV certificate immediate issuance

Warning

On May 16, 2023, DigiCert changed the default behavior for DV TLS/SSL orders in CertCentral accounts using AuthKeys.

Starting May 16, 2023, DV TLS certificate orders created with the CertCentral Services API always use a default value of false for the use_auth_key request parameter. From May 16 onward, to validate domains on a DV order using AuthKey request tokens, you must include the use_auth_key parameter with a true value in the body of your certificate request.

To learn more about this change, see our change log entry.

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

Notice

Requests for Encryption Everywhere DV certificates require an AuthKey request token for DCV checks. To request Encryption Everywhere DV certificates, you must follow these steps and configure an AuthKey for your account.

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.

Note

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.

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.

Notice

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

Step 3: Create a timestamp

The timestamp determines the starting date and time (UTC) of the 30-day validity period for the request token. 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.

Note

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:

yyyyMMddhhmmss

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

Step 4: Generate a request token

Important

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:

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

Note

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

Note

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

    Note

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

  4. Submit your 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.

In the JSON request body:

  • Include the use_auth_key parameter with a true value.

    Note

    For Encryption Everywhere DV certificates, the use_auth_key parameter is ignored. When requesting an Encryption Everywhere certificate, if an AuthKey exists for the account, DigiCert always checks the DNS records for an AuthKey request token. If no AuthKey exists for the account, or if DigiCert doesn't find a valid AuthKey request token for one or more domains on the order, the API returns an error.

  • Make sure the value of the dcv_method request parameter corresponds with the location of the request token.

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.

Note

If any of the prerequisites are missing, immediate issuance won't happen.

What if DigiCert can’t immediately issue the certificate?

If domain control validation (DCV) cannot be completed for one or more domains on the order, the API returns an error. Make sure the AuthKey request token is valid and placed at the right location for each domain. Then, try again.

If it takes longer than expected to process the certificate request, the API returns the standard response for DV orders created in a pending state, omitting the certificate_chain:

{ 
  "id": 112233,
  "certificate_id": 113
} 

To prevent failures caused by issuance delays, design your integration to account for the possibility of a pending order response.

When the API returns the response for a pending order, use one of these these methods to find out when the certificate is ready to download:

Then, when the order status becomes issued, download the certificate: