DV certificate lifecycle

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

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

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

...
  "order_validity": {
    "custom_expiration_date": "09 JUN 2025"
  },
...

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

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

...
  "certificate": {
    ...
    "cert_validity": {
      "custom_expiration_date": "01 MAY 2021"
    }
  },
...

"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"
  }
]

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

To use ICA selection:

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"
}

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:

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
        }
    },
    "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 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.

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.

With the random value added to the DNS TXT record (DNS TXT method), DNS CNAME record (DNS CNAME method), or to the fileauth.txt uploaded to the specified location (HTTP TXT 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 Check order DCV endpoint.

A PUT to this endpoint returns four possible responses:

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:

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.

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:

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,
    "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"
    }
}'

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. You can revoke a certificate using one of two endpoints. Both endpoints use the same request body parameters.

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.

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
}'

// 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!"
}