Skip to main content

Revoke certificate

PUT https://www.digicert.com/services/v2/certificate/{{certificate_identifier}}/revoke

Use this endpoint to submit a request to revoke a single certificate on an order. In the endpoint path, replace certificate_identifier with the certificate ID or serial number of the certificate to revoke.

To submit a request to revoke the entire order, use the Revoke order certificates endpoint.

Danger

Revoking a certificate is permanent. For most implementations, revoking a code signing or document signing certificate invalidates past signatures and timestamps on code or documents signed by the certificate.

Notice

Certificates with a pending reissue order cannot be revoked. To revoke a certificate with a pending reissue, either cancel the reissue request or revoke the certificate after the reissue is complete.

Skip the approval step

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.

What happens if I revoke a certificate on an order with only a single certificate?

When you revoke a certificate on an order with only a single certificate:

  • The order is still active.

  • You can still reissue a certificate on that order.

    If you do not plan to reissue a certificate for the order, use the Revoke order certificates endpoint to submit a request to revoke the order.

  • No refund is provided for a revoked certificate on an order.

To change this behavior such that revoking the only certificate on the order also revokes the entire order, follow these steps:

  1. Sign in to your CertCentral account.

  2. In the left menu, go to Settings > Preferences.

  3. On the Preferences page, expand Advanced settings.

  4. Under Certificate Revocations (API Only), select Revoke order when all certificates are revoked.

    This setting only applies to the Revoke certificate endpoint in the Services API. To revert to the default behavior, select Revoke individual certificates.

  5. Scroll to the bottom of the page and click Save Settings.

Example requests and responses

Example 1. Skip approval step (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
}'

Example 2. Create revocation request (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 '{
  "comments": "I no longer need this certificate."
}'

Example 3. 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 '{
  "revocation_reason": "superseded",
  "skip_approval": true
}'

Path parameters

Name

Req/Opt

Description

certificate_identifier

required

Value that identifies the certificate to revoke. Accepts the certificate ID or serial number.

Request parameters

Name

Req/Opt

Type

Description

revocation_reason

optional

string

Reason you want to revoke the certificate.

Only used in requests to revoke TLS/SSL certificates. Ignored in revocation requests for other certificate types.

Allowed values:

  • unspecified (default): None of the other reasons apply.

  • keyCompromise: The private key associated with the certificate has been lost, stolen, or otherwise compromised.

  • affiliationChanged: The organization name or any other organizational information in the certificate has changed.

  • superseded: The certificate has been replaced by another certificate.

  • cessationOfOperation: The domain is no longer active or managed by your organization, or you no longer use the certificate.

comment

optional

string

Message to associate with the revocation request. Use this field to add a comment to the request for the request approver.

Note: DigiCert only stores the comment value on revocation requests. If skip_approval is true and the requestor has admin privileges, DigiCert revokes the certificate without creating a request, and we do not store the comment value.

skip_approval

optional

bool

If true, the revoke request skips the approval step and is immediately submitted to DigiCert for revocation. Otherwise, false (default).

Note: For skip approvals to work, the API key must have admin privileges.

Response parameters

Note

If you skip the approval step, the API returns a status of 204 (No Content) instead of these fields.

Name

Type

Description

id

int

Request ID.

date

string

Timestamp of when the revoke request was submitted.

Format: UTC timezone and ISO 8601 date

type

string

Request type.

Possible values: revoke

status

string

Status of the revoke request.

Possible values: submitted, pending, approved, rejected

requester

object

Details about the user that placed the request. See Structures – User details object.

.. id

int

User ID.

.. first_name

string

First name of user.

.. last_name

string

Last name of user.

.. email

string

Email address of user.

comments

string

Message about the revoke request.

In this section: