The DV certificate lifecycle consists of these main steps:
Once a certificate has been issued, you can perform any of these actions:
In order to construct your request body and submit an order request, you need to collect some key pieces of information:
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.
Parameter | Type | Description |
---|---|---|
common_name
|
string | Primary domain to be secured by the certificate. |
dns_names
|
array |
Any additional domains to be secured by the certificate. Adding domains to this parameter may incur additional costs. |
All DV certificate orders include a 'plus' feature that allow you to cover both the root and www subdomain of your domain at no added cost. When constructing your request body, add the base domain ([your-domain].com) to the common_name
parameter and then the other version of the domain (www.[your-domain].com) to the dns_names
array.
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.
The Services API does not extract information from the CSR to fill in the details of a certificate request. You must provide values for all relevant request parameters, including certificate.common_name
and certificate.dns_names
.
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.
DigiCert's public SSL/TLS certificates support orders for Multi-year Plans. With Multi-year Plans, you pick the SSL/TLS certificate, the certificate validity period, and the duration of coverage you want (up to six years). Until the order expires, you reissue the certificate at no additional cost each time it reaches the end of its validity period. For more information, see Multi-year Plans.
Enterprise License Agreement (ELA) and Flat Fee contracts only support 1- and 2-year Multi-year Plans.
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 six 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.
Name | Req/Opt | Type | Description |
---|---|---|---|
order_validity | required* | object |
Defines the validity period of the order. Order validity determines the length of a Multi-year Plan. *Requests must include a value for either the order_validity object or for one of the top-level order validity parameters (validity_years , validity_days , or custom_expiration_date ). The values you provide in the order_validity object override the top-level validity parameters.
|
.. years | required* | int |
Number of years the order is valid. *Can be replaced by order_validity.days or order_validity.custom_expiration_date .Range: 1 -6
|
.. days | optional | int |
Number of days the order is valid. Overrides order_validity.years .Max: 2190
|
.. custom_expiration_date | optional | string |
Custom expiration date for the order. Overrides order_validity.days and order_validity.years .Format: dd MMM YYYY (for example, "09 JUN 2025" )Range: Must be within six years of the date you request the order. |
For example:
...
"order_validity": {
"years": 2
},
...
...
"order_validity": {
"days": 900
},
...
...
"order_validity": {
"custom_expiration_date": "09 JUN 2025"
},
...
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.
Name | Req/Opt | Type | Description |
---|---|---|---|
certificate | required | object | Certificate details. |
.. cert_validity | optional | object |
Defines the validity period of the first certificate issued for this order. Cannot exceed order validity period. If not provided, the certificate's validity period defaults to the validity period of the order or the maximum certificate validity period defined by CA/B Forum baseline requirements, whichever is shorter. This object is not used for requests from accounts that do not have Multi-year Plans enabled. |
.. .. years | optional | int |
Number of years the certificate is valid after it is issued. Can be replaced with cert_validity.days or cert_validity.custom_expiration_date .Allowed values: 1
|
.. .. days | optional | int |
Number of days the certificate is valid after it is issued. Overrides cert_validity.years .Max: 397
|
.. .. custom_expiration_date | optional | string |
A custom expiration date for the certificate. Overrides cert_validity.days and cert_validity.years .Format: dd MMM YYYY (for example, "09 JUN 2021" )Range: Must be within 397 days of the date you request the certificate. |
For example:
...
"certificate": {
...
"cert_validity": {
"years": 1
}
},
...
...
"certificate": {
...
"cert_validity": {
"days": 100
}
},
...
...
"certificate": {
...
"cert_validity": {
"custom_expiration_date": "01 MAY 2021"
}
},
...
Email DCV is the default DCV method used for DV certificate orders. If desired, you can change the default DCV method by including the dcv_method
parameter in the request body. The dcv_method
parameter accepts these values:
Value | Description |
---|---|
email
|
Sends DCV emails to any email address (e.g., administrator and technical contacts) we find in the domain’s WHOIS record and to the five constructed email addresses for the domain (admin, administrator, webmaster, hostmaster, and postmaster @[domain_name]). When using this method, you can define a specific email scope by including the dcv_emails object.
|
dns‑txt‑token
|
Returns a random value token in the response body to be added to a DNS TXT record on the domain. Using this method requires the ability to modify domain DNS records. |
http‑token
|
Returns a random value token in the response body to be placed in a .txt file on the website to be secured by the certificate. Using this method requires the ability to upload files to the web server. |
See Domain Control Validation (DCV) Methods for more information about different DCV methods and how to complete them.
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 specified in the domain’s WHOIS record 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].
"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"
}
]
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:
Endpoint | SSL products |
---|---|
Order SSL (type_hint) | This endpoint attempts to determine the appropriate SSL product based on the information you provide in the request body. |
Order DV SSL | GeoTrust Standard DV SSL, RapidSSL Standard DV SSL, GeoTrust Wildcard DV SSL, RapidSSL Wildcard DV SSL, and GeoTrust Cloud DV certificates |
Order GeoTrust DV SSL | GeoTrust DV SSL certificate |
Order Multi-year Plan | Order a Multi-year Plan for a flex certificate. |
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.certificate_id
– The ID of the certificate.dcv_random_value
– Randomly generated token used for dns-txt-token and http-token DCV methods. 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.
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
}
},
"custom_expiration_date": "",
"comments": "Message for the approver.",
"container": {
"id": 69748
},
"custom_renewal_message": "Renew me.",
"skip_approval": true,
"disable_ct": 0,
"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"
}
}'
{
"id": 112233,
"certificate_id": 123456
}
{
"id": 112233,
"certificate_id": 123456,
"dcv_random_value": "icru1984rnekfj"
}
After submitting the order, you can use the Order info endpoint to get order details and review the submitted information.
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.
The status
parameter only allows a value of CANCELED
(case sensitive).
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."
}'
// empty
With the DV order submitted, you now need to prove control over the domains on the order.
Regardless of the DCV method chosen, you must complete the DCV for each domain to be secured by the certificate. For example, if dns-txt-token
method was chosen, you must create a DNS TXT record for each domain on the order.
If the dcv_emails
array was included in the response body, then DCV emails are sent to the addresses defined in the array. Otherwise, DCV emails are sent to these addresses:
To complete email DCV, in your email client inbox locate the email with the subject [Action Required] Approve Certificate Request for [yourdomain] {Order #} and follow the instructions.
If you need to resend the DCV emails for a submitted order, you can use the DV SSL: Resend emails endpoint (replace the {{order_id}} placeholder with the order ID returned in the response body when you submitted the order).
If you no longer have the random value or need to generate a new one, you can use the DV SSL: Generate DCV token endpoint, replacing the {{order_id}} placeholder with the order ID that was included in the response body when you submitted the order.
Follow these steps to complete DNS TXT DCV and demonstrate control over your domains:
dcv_random_value
that was returned in the response body when the order was placed.Once you've added the DNS TXT record for all domains on the order, you're ready to have us verify the TXT records (see Check DCV).
Follow these steps to complete HTTP token DCV and demonstrate control over your domains:
dcv_random_value
that was returned in the response body when the order was placed.With the random token added to the DNS TXT record (DNS TXT method) or the fileauth.txt uploaded to the specified location (HTTP DCV method) for each domain on the order, you're ready to perform a DCV check.
When you submit your certificate order, automatic domain control validation (DCV) polling begins immediately and runs for one week. 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:
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.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}}'
{
"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."
}
]
}
After submitting your order and completing the DCV for each domain, you'll want to know when the order status changes and the certificate is ready to download. The best way to do this is with a GET to the Status change list endpoint.
A GET to this endpoint returns three possible responses:
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.{}
) means no orders have had a status change in the specified timeframe. Either increase the timeframe or wait to send another request.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).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}}'
{
"orders": [
{
"order_id": 112233,
"certificate_id": 123456,
"status": "issued"
}
]
}
{}
{
"errors": [
{
"code": "time_frame_too_long",
"message": "An error occurred while processing your request."
}
]
}
Once the order status changes from pending to issued, your certificate is ready to be downloaded. Depending on your needs, there are four endpoints you can use to download your 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:
Even if some of the above details are staying the same, you still need to include it in the reissue request.
Note that certain changes, such as adding additional SANs ('dns_names') may incur additional costs.
It may be necessary to perform DCV for some or all of the domains.
The Reissue certificate endpoint accepts the following optional parameters:
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
}
}'
{
"id": 112233,
"requests": [
{
"id": 332211
}
]
}
{
"id": 112233,
"certificate_id": 111112
}
After a reissue is complete, download the new certificate (see Download DV Certificate).
You can get a complete reissue history for an order by using the List reissues endpoint.
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:
Name | Type | Description |
---|---|---|
renewed_thumbprint | string | The SHA-1 thumbprint of the previous order's primary certificate. For more information, see How to check a certificate's thumbprint. |
renewal_of_order_id | int | If order is a renewal, enter the previous order's ID. |
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
}
},
"custom_expiration_date": "",
"comments": "Message for the approver.",
"container": {
"id": 69748
},
"custom_renewal_message": "Renew me.",
"skip_approval": true,
"disable_ct": 0,
"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"
}
}'
Certain changes, such as adding additional SANs (dns_names
), may incur additional costs. You may need to perform DCV for some or all of the domains.
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.
Once your order is issued, you can submit a revoke request if needed.
All revocation requests must be approved by an administrator in CertCentral before DigiCert will revoke the certificate. This approval step is required and cannot be skipped.
You can revoke a certificate using one of two endpoints:
Both endpoints use the same request body parameters.
After submitting the revocation request, the request needs to be approved by an administrator using the Update request status endpoint.
curl -X PUT \
'https://www.digicert.com/services/v2/certificate/{{certificate_id}}/revoke' \
-H 'Content-Type: application/json' \
-H 'X-DC-DEVKEY: {{api_key}}' \
-d '{
"comments": "I no longer need this cert."
}'
{
"id": 1,
"date": "2016-02-10T17:06:15+00:00",
"type": "revoke",
"status": "pending",
"requester": {
"id": 14,
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@digicert.com"
},
"comments": "I no longer need this cert."
}