DV certificate lifecycle

The DV certificate lifecycle consists of these main steps:

• Prepare DV certificate request
• Submit DV certificate order
• (Optional) Cancel certificate order
• Complete domain control validation (DCV)
• Check order status
• Download issued certificate

Once a certificate has been issued, you can perform any of these actions:

• Reissue a certificate
• Renew DV certificate
• Revoke a certificate

Prepare DV certificate request

In order to construct your request body and submit an order request, you need to collect some key pieces of information:

• Domain names to be secured by the certificate
• Certificate signing request (CSR) generated on the server where the certificate will be installed
• Validity period of the certificate (amount of time the certificate should be valid)
• DCV method to use when demonstrating control over the domains

Domain names

Once you’ve collected the domain name(s) to be secured by the certificate, they should be entered in one of two request body parameters.

Certificate signing request (CSR)

The CSR should be generated on the server where the certificate will be installed. Once generated, enter the PEM formatted CSR in the csr parameter of the request body. See Create a CSR (Certificate Signing Request) for additional information.

Validity periods

When you submit an order request, you set a validity period for the certificate and for the order. The validity period of the certificate determines when the certificate expires. The validity period of the order determines how long you can reissue the certificate without additional costs.

Order validity period

Use the order_validity object in your request body to customize the number of years or days the order is valid, or to set a custom expiration date for the order. Orders for Multi-year Plans can be valid for up to three years.

Order validity can be greater than certificate validity. If you do not specify a custom certificate validity period, we issue the certificate using the validity period of the order or the maximum certificate validity period defined in the CA/B Forum baseline requirements, whichever is shorter.

For example:

• order_validity.years
• order_validity.days
• order_validity.custom_expiration_date

...
  "order_validity": {
    "years": 1
  },
...

...
  "order_validity": {
    "days": 199 
  },
...

...
  "order_validity": {
    "custom_expiration_date": "2026-12-26"
  },
...

(Optional) Certificate validity period

Use the optional certificate.cert_validity object in your request body to customize the number of years or days the certificate is valid, or to set a custom expiration date for the certificate.

For example:

• certificate.cert_validity.years
• certificate.cert_validity.days
• certificate.cert_validity.custom_expiration_date

...
  "certificate": {
    ...
    "cert_validity": {
      "years": 1
    }
  },
...

...
  "certificate": {
    ...
    "cert_validity": {
      "days": 199
    }
  },
...

...
  "certificate": {
    ...
    "cert_validity": {
      "custom_expiration_date": "2026-12-26"
    }
  },
...

Choose a DCV method

Email DCV is the default DCV method used for public TLS/SSL certificate orders. To use a different DCV method, it is recommended to include the dcv_method parameter in your order request. To check the DCV methods available to your account, see List DCV methods.

Use the table below to compare the available DCV methods and determine the right value for the dcv_method parameter:

(Optional) dcv_emails array

When using the email DCV method, it’s possible to specify the email addresses that should be used when sending the DCV emails. To do this, include the dcv_emails array in the request body and add an entry for each domain on the order.

When using this parameter, entered email addresses must be one of the allowed DCV email addresses for the domain or or be one of the default email addresses for the domain (defined by industry standards as: admin, administrator, webmaster, hostmaster, and/or postmaster @[domain_name]). In addition, we will only send the DCV email to the addresses specified.

For example, if you specify john.doe@[domain_name], we will not send DCV emails to any of the default email addresses. Or if you specify admin@[domain.com], we will not send the DCV email to john.doe@[domain_name].

Example dcv_emails array

"dcv_emails": [
  { 
    "dns_name": "example.com",
    "email_domain": "example.com",
    "email": "hostname@example.com"
  },
  { 
    "dns_name": "my.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  },
  { 
    "dns_name": "another.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  }
]

(Optional) ICA selection

With ICA selection, you can choose which ICA certificate chain should issue your end-entity certificate.

To use ICA selection:

• ICA selection must be enabled for your account. To enable ICA selection, contact your account manager or the Support team. For more information, see ICA certificate chain option for public TLS certificates.
• You must know the ca_cert_id of the ICA that you want to issue your certificate. To find the ca_cert_id for an ICA certificate chain, use the Product list endpoint.

To select an ICA certificate chain, include the certificate.ca_cert_id parameter in your certificate request. The value of this parameter is the ID of the ICA certificate chain that should issue your end-entity certificate.

For example:

{
  "certificate": {
    "common_name": "example.test.com",
    "csr": {{csr}},
    "signature_hash": "sha256",
    "ca_cert_id": "4A7259E3E5D112A"
  },
  "order_validity": {
    "years": 1
  },
  "locale": "en",
  "skip_approval": true,
  "payment_method": "profile"
}

Submit DV certificate order

After you collect the above information, you’re ready to construct your request body and submit your order request. To do this, submit a POST request to the order endpoint for the type of certificate you want to buy.

The following table lists the endpoints for ordering different DV SSL products:

A successful POST to an order endpoint returns a 201 Created HTTP response code. The response body includes information that you can use to check the status of the order and to download the certificate when it is issued, including:

• id: The ID of the order in your account. Use this ID with the Order info endpoint to check the details of the order.
• certificate_id: The ID of the certificate. Use this ID to perform operations such as downloading or revoking the certificate.
• dcv_random_value: Randomly generated token used for the dns-txt-token, dns-cname-token, and http-token DCV methods. Not used for persistent-txt, which uses a persistent URI. This token expires after 30 days.

The example below shows the entire request and response bodies for a sample request to the Order DV SSL endpoint. For more info about each parameter used in the request body, see the Order DV SSL – Request parameters table.

Request DV certificate (cURL)

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",
        "dns_names": [
        	"sub.example.com",
        	"log.example.com"
        ],
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }    
        "cert_validity": {
            "days": 199
        }
    },
    "container": {
        "id": 69748
    },
    "custom_renewal_message": "Renew me.",
    "skip_approval": true,    
    "order_validity": {
        "years": 1
    },
    "custom_fields": [
        {
            "metadata_id": 12,
            "value": "Invoice #12345"
        }
    ],
    "payment_method": "balance",
    "dcv_method": "email",
    "dcv_emails": [
    	{
    		"dns_name": "example.com",
    		"email_domain": "example.com",
    		"email": "admin@example.com"
    	},
    	{
    		"dns_name": "sub.example.com",
    		"email_domain": "example.com",
    		"email": "jim.smith@example.com"
    	},
    	{
    		"dns_name": "log.example.com",
    		"email_domain": "example.com",
    		"email": "it@example.com"
    	}
    ],
    "locale": "en",
    "technical_contact": {
        "first_name": "Jim",
        "last_name": "Smith",
        "telephone": "555-555-5555",
        "job_title": "IT Admin",
        "email": "jim.smith@example.com"
    }
}'

• 201 Created (email)
• 201 Created (dns-txt-token or http-token)

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

{
  "id": 112233,
  "certificate_id": 123456,
  "dcv_random_value": "icru1984rnekfj"
}

(Optional) Cancel certificate order

After placing an order, there may be times when you need to cancel it. To cancel an order, you need to change the status from pending to canceled. This is done with a PUT to the Update order status endpoint.

A successful PUT to this endpoint returns a 204 No Content HTTP response.

Cancel certificate order (cURL)

curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/status' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "status": "CANCELED",
    "note": "Message about the cancellation."
}'

204 No Content (Order canceled)

// empty

Complete domain control validation (DCV)

After submitting the DV certificate order, complete DCV for each domain on the order or any domain that does not have a current validation. The DCV method you selected when creating the order determines how you demonstrate control over each domain.

Complete DCV for the domain(s) that still require validation using the method selected when preparing the request. A domain with an active validation may not need another DCV check. To review a domain’s validation status, see Validation details.

For guidance on completing the domain control validation, see DCV Methods.

Choose a DCV method (email, DNS, or HTTP) and then complete validation by responding to the email, updating DNS records, or updating the host validation file accordingly. For the persistent-txt DCV method, keep the persistent DNS TXT record and URI in your domain’s DNS configuration so DigiCert can reuse them for future domain validations. Validating a domain using the email, dns-txt-token, dns-cname-token, or persistent-txt DCV method demonstrates control over the domain and its subdomains. Using only the file-based (http-token) DCV method demonstrates control over the exact FQDN in your request.

Key DCV related tasks you can perform with CertCentral APIs:

• For viewing the available DCV methods for a domain, see List DCV methods.
• For checking DCV status, see Validation details.
• To retrieve the existing DCV random value or generate a replacement if it has expired, using the Order ID, see Generate DCV token.
• For generating a new random value for an individual domain using the Domain ID, see OV/EV SSL: Generate DCV token, which also supports DV orders. To retrieve an existing random value instead of generating a new one, see Domain info endpoint.
• For completing http-token DCV, see File-based domain control validation (http-token).
• For certificate renewals or reissuances, domain revalidation may be necessary if the prior validation period has lapsed. See Submit domain for validation.
• To resend an email validation request, use Resend DCV email with the domain ID.

Key DCV related tasks you can perform with the CertCentral UI:

• For completing DCV through the CertCentral UI, see Domain Control Validation using CertCentral platform documentation.

Perform DCV check

When you submit your certificate order, DigiCert automatically checks the domain for the required DCV information. For more information about automatic DCV polling, see Automatic domain control validation checks.

In addition to automatic DCV polling, you can perform a DCV check manually with a PUT to the DV SSL: Check DCV endpoint.

A PUT to this endpoint returns four possible responses:

• 200 OK – DCV completed successfully
• 400 Bad Request – There are three possible error codes with this response:
  • invalid_dns_txt: DNS TXT record could not be found or contains the wrong random value for one or more domains. Verify that all domains on the order have the appropriate DNS TXT record with the correct random value.
  • file_random_value_not_found: fileauth.txt could not be found or contains the wrong random value for one or more domains. Verify that for all domains on the order the file is in the correct directory, is publicly available, and contains the correct random value.
  • invalid_dns_method: The DCV method for the order is set to email. Either locate the sent email and complete the DCV instructions or change the DCV method.

Perform DCV check (cURL)

curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/check-dcv' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'

• 200 OK (DCV status)
• 400 Bad Request (dns-txt-token)
• 400 Bad Request (http-token)
• 400 Bad Request (email)

{
  "order_status": "pending",
  "certificate_id": 123456,
  "dcv_status": "valid"
}

{
  "errors": [
    {
      "code": "invalid_dns_txt",
      "message": "Could not find a valid TXT record for one or more domains."
    }
  ]
}

{
  "errors": [
    {
      "code": "file_random_value_not_found",
      "message": "Could not find the random value at the expected file location for one or more domains."
    }
  ]
}

{
  "errors": [
    {
      "code": "invalid_dns_method",
      "message": "An error occurred while processing your request."
    }
  ]
}

Check order status

After submitting your order and completing the DCV for each domain, you’ll want to know when the order status changes and whether DigiCert has issued the certificate.

To check the status of your order, use the GET /order/certificate/{order_id} endpoint. Check the value of the Status response parameter to get the current status of the order. For more information about retrieving order information, see Order info. For more information about types of order status, see Glossary - Order Status.

The best way to determine when an order’s status changes is to send a GET request to the Status change list endpoint. A GET to this endpoint returns three possible responses:

• 200 OK (orders array) – The orders array lists all orders that have changed status in the specified timeframe. When your order’s status changes from pending to issued, it will appear in the list. If multiple orders are returned, use either the order ID or certificate ID to locate the order.
• 200 OK (empty object) – A response with an empty object ({}) means no orders have had a status change in the specified timeframe. Either increase the timeframe or wait to send another request.
• 400 Bad Request – A response with the time_frame_too_long error code means the timeframe specified in the URL query string exceeds the maximum value. Reduce the timeframe to a value less than 10080 minutes (7 days).

Check order status (cURL)

curl -X GET \
  'https://www.digicert.com/services/v2/order/certificate/status-changes?minutes=10' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'

• 200 OK (Orders list)
• 200 OK (no orders found)
• 400 Bad Request (time_frame_too_long)

{
  "orders": [
    {
      "order_id": 112233,
      "certificate_id": 123456,
      "status": "issued"
    }
  ]
}

{}

{
  "errors": [
    {
      "code": "time_frame_too_long",
      "message": "An error occurred while processing your request."
    }
  ]
}

Download certificate

Once the order status changes from pending to issued, your certificate is ready to be downloaded. Depending on your needs, you can use any of the following endpoints to download your certificate.

To download a certificate, use the GET /certificate/{certificate_id}/download/ endpoint after the certificate is issued. You can download certificates for a specific platform, in a supported format or by order ID.

For more information about downloading the certificate for a platform, see Download certificate for a platform.

For more information about downloading the certificate in a specific format, see Download certificate by format.

For more information about downloading the certificate based on the order ID, see Download certificate (order_id).

For more information about downloading the certificate using its order ID in a specific format, see Download certificate by format (order_id).

Reissue DV certificate

Reissuing a certificate allows you to add, remove, or swap domain names, update the CSR, or change the signature hash of a certificate without submitting a new order. Additionally, if a certificate expires before the end of an order, you can reissue the certificate to receive a new certificate with a new expiration date.

A reissued certificate has a new certificate ID but the same order ID. After a reissue is approved, a new certificate is issued and needs to be reinstalled.

When reissuing a certificate, you need to provide this information:

• Common name
• SANs (include both the current SANs in the dns_names parameter as well as any additional SANs to be secured)
• CSR (to get and reuse the current CSR, use the Request info endpoint)
• Server platform ID (options listed here)

Even if some of the above details are staying the same, you still need to include it in the reissue request.

The Reissue certificate endpoint accepts the following optional parameters:

• skip_approval: Allows the request to be immediately submitted for validation, bypassing the need to approve the reissue request.

Reissue DV certificate (cURL)

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/reissue' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
  "certificate": {
    "common_name": "example.com",
    "dns_names": [
        "sub.example.com"
    ],
    "csr": "<csr>",
    "server_platform": {
      "id": 2
    },
    "signature_hash": "sha256"
    "skip_approval": true
  }
}'

• 201 Created (skip_approval = false)
• 201 Created (skip_approval = true)

{
  "id": 112233,
  "requests": [
    {
      "id": 332211
    }
  ]
}

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

After a reissue is complete, download the new certificate (see Download Certificate).

You can get a complete reissue history for an order by using the List reissues endpoint.

Renew DV order

Renewing an order allows you to link a new order to an expiring order such that you can track the history of your certificates using CertCentral and the Services API. When you renew an order, you receive a new certificate and a new order ID.

To renew, send a request to the endpoint for the certificate you want to buy. Follow the instructions to prepare the certificate request, and include a value for one of the following parameters:

For example, a request to renew the order with ID 123456 looks like this:

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",
        "dns_names": [
        	"sub.example.com",
        	"log.example.com"
        ],
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }
    },
    "container": {
        "id": 69748
    },
    "custom_renewal_message": "Renew me.",
    "skip_approval": true,    
    "order_validity": {
        "years": 1
    },
    "custom_fields": [
        {
            "metadata_id": 12,
            "value": "Invoice #12345"
        }
    ],
    "renewal_of_order_id": 123456,
    "payment_method": "balance",
    "dcv_method": "email",
    "dcv_emails": [
    	{
    		"dns_name": "example.com",
    		"email_domain": "example.com",
    		"email": "admin@example.com"
    	},
    	{
    		"dns_name": "sub.example.com",
    		"email_domain": "example.com",
    		"email": "jim.smith@example.com"
    	},
    	{
    		"dns_name": "log.example.com",
    		"email_domain": "example.com",
    		"email": "it@example.com"
    	}
    ],
    "locale": "en",
    "technical_contact": {
        "first_name": "Jim",
        "last_name": "Smith",
        "telephone": "555-555-5555",
        "job_title": "IT Admin",
        "email": "jim.smith@example.com"
    }
}'

For renewal orders, the Order info response includes a true value for the is_renewal parameter. The value of the renewed_order_id parameter is the order ID for the previous order:

{
    "is_renewal": true,
    "renewed_order_id": 123456
}

After the status of the order renewal changes from pending to issued, you can download the new certificate (see Download certificate) and install it on your server. For more information about installing your certificate, see our SSL Certificate Installation Instructions & Tutorials page.

Revoke certificate

Once your order is issued, you can submit a revoke request if needed. You can revoke a certificate using one of two endpoints. Both endpoints use the same request body parameters.

• Revoke certificate – Use this endpoint to revoke a specific certificate using the certificate ID or serial number.
• Revoke order certificate – Use this endpoint to revoke all certificates associated with an order ID.

After submitting the request, an administrator must approve it before DigiCert can revoke the certificate.

To skip the approval step and submit the request directly to DigiCert for revocation, include "skip_approval": true in the body of your request. To skip the approval step, the API key must have admin privileges. See Authentication.

• Skip approval step (cURL)
• Create revocation request (cURL)
• Include revocation reason (cURL)

curl --request PUT 'https://www.digicert.com/services/v2/certificate/{{certificate_identifier}}/revoke' \
--header 'Content-Type: application/json' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--data-raw '{
  "skip_approval": true
}'

curl --request PUT 'https://www.digicert.com/services/v2/certificate/{{certificate_identifier}}/revoke' \
--header 'Content-Type: application/json' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--data-raw '{
  "comments": "I no longer need this certificate."
}'

curl --request PUT 'https://www.digicert.com/services/v2/certificate/{{certificate_identifier}}/revoke' \
--header 'Content-Type: application/json' \
--header 'X-DC-DEVKEY: {{api_key}}' \
--data-raw '{
  "revocation_reason": "superseded",
  "skip_approval": true
}'

• 204 No Content (Skip approval step)
• 201 Created (Create revocation request)

// empty

{
  "id": 1,
  "date": "2016-02-10T17:06:15+00:00",
  "type": "revoke",
  "status": "pending",
  "requester": {
    "id": 242140,
    "first_name": "Jack",
    "last_name": "White",
    "email": "j.white@fakeaddy.com"
  },
  "comments": "Revoked via API!"
}