The OV/EV 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 OV/EV certificate orders allow you to include a specific additional SAN on single domain certificates for free. 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.
When ordering a certificate, you are required to specify the certificate validity period. You can use any of these parameters to determine how long a certificate will be valid.
| Parameter | Type | Description |
|---|---|---|
validity_years
|
int |
Use this parameter when specifying certificate validity in years. Allowed values: 1, 2
|
validity_days
|
int | Use this parameter when specifying certificate validity in days. |
custom_expiration_date
|
string |
Use this parameter to specify a specific date the certificate should expire. Format: yyyy-MM-dd
|
If more than one validity parameter is included in the request body, we prioritize them as follows: custom_expiration_date > validity_days > validity_years.
Email DCV is the default DCV method used for OV/EV 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 required 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"
}
]Now that you've collected the above information, you're ready to construct your request body and submit your order request. This is done with a POST to the Order OV/EV SSL endpoint. Note that the Secure Site product line is ordered through a separate endpoint.
The organization details and contact are submitted here in the organization object. If the organization already has an assigned ID, you can simply pass it with the string id instead of providing the full organization information.
A successful POST to this endpoint returns a 201 Created HTTP response code. The response body includes some key pieces of information that is used to check the status of the order as well as download the certificate once it has been issued.
id – Order ID used to check order details and perform DCV actions.certificate_id – Certificate ID used to download the issued certificate.dcv_random_value – Randomly generated token used for dns-txt-token and http-token DCV methods. This token expires after 30 days.For more info about each parameter used in the request body, see the Order OV/EV SSL – Request parameters table.
curl -X POST \
'https://www.digicert.com/services/v2/order/certificate/{{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",
"app.example.com"
],
"csr": "<csr>",
"server_platform": {
"id": 45
},
"signature_hash": "sha256",
"organization_units": [
"Accounting department"
]
},
"validity_years": 2,
"comments": "Message for the approver",
"disable_renewal_notifications": true,
"locale": "en",
"dcv_emails": [
{
"dns_name": "example.com",
"email_domain": "example.com",
"email": "hostname@example.com"
},
{
"dns_name": "sub.example.com",
"email_domain": "example.com",
"email": "admin@example.com"
},
{
"dns_name": "app.example.com",
"email_domain": "example.com",
"email": "admin@example.com"
}
]
"payment_method": "balance",
"organization": {
"name": "Epigyne Unwieldiness llc",
"assumed_name": "Epigyne Unwieldiness",
"country": "us",
"address": "932 Prospect Street",
"address2": "Floor 08",
"city": "Minneapolis",
"state": "mn",
"zip": "40849",
"telephone": "666-186-6450",
"container": {
"id": 93288
},
"organization_contact": {
"first_name": "Gia",
"last_name": "Booth",
"job_title": "Clinical Laboratory Technician",
"email": "gia.booth@inbox.com",
"telephone": "666-186-6450",
"telephone_extension": "736"
}
},
"custom_fields": [
{
"metadata_id": 11,
"value": "Invoice #00001"
}
]
}'{
"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."
}'// emptyWith the OV/EV 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 Resend emails endpoint (replace the {{order_id}} placeholder with the order ID returned 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 generated when the order was placed. For OV/EV orders, you can retrieve this value by using the Domain info endpoint and including the include_dcv=true URL query string.Once you've added the DNS TXT record for all domains on the order, you're ready to have us verify the TXT records.
Follow these steps to complete HTTP token DCV and demonstrate control over your domains:
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. This is done via the Order Detail page in CertCentral.
In the Order status section of the page, click on each domain still listed as pending DCV, and then click "Check" to have the DCV method checked and confirmed.
In addition to domain validation, all OV/EV orders also require organization validation. Once an order is submitted, DigiCert's validation team will begin working on the OV/EV organization validation process.
Both organization and domain validation must be complete before the certificate can be issued.
You can check the current validation status for an organization with a GET to the Organization Validation details endpoint.
A successful GET to this endpoint returns a 200 OK HTTP response.
curl -X GET \
'https://www.digicert.com/services/v2/organization/{{organization_id}}/validation' \
-H 'Content-Type: application/json' \
-H 'X-DC-DEVKEY: {{api_key}}'{
"validations": [
{
"type": "ov",
"name": "OV",
"description": "Normal Organization Validation",
"status": "pending"
},
{
"type": "ev",
"name": "EV",
"description": "Extended Organization Validation (EV)",
"status": "pending",
"verified_users": [
{
"id": 12,
"first_name": "John",
"last_name": "Smith"
}
]
}
]
}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. A reissued certificate will have 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 Certificate).
You can get a complete reissue history for an order by using the List reissues endpoint.
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 my 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."
}