POST Certificates/Revoke

Sends a revocation request to the certificate CA.

TIP  Make sure the Certificate object is currently enrolled and not in error or a pending workflow at or before Stage 700. Otherwise, Certificates/Revoke returns Certificate [ CertificateDN] does not have a certificate to revoke.

To get the certificate status call GET Certificates with the appropriate Certificates status filters.

Requirements

  • Permissions:  The caller must have Write permission to the Certificate object.
  • Token scope:  Certificate:Revoke

Headers

  • Content type: Content-Type:application/json.

  • Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Specify CertificateDN or Thumbprint.

Input parameters

Name

Description

CertificateDN (Optional)

The Distinguished Name (DN) of the certificate to revoke.

Thumbprint (Optional)

The thumbprint (hash) of the certificate to revoke. To get the thumbprint, call GET Certificates/{guid}.

Reason (Optional)

The reason for revocation of the certificate:

  • 0: None
  • 1: User key compromised
  • 2: CA key compromised
  • 3: User changed affiliation
  • 4: Certificate superseded
  • 5: Original use no longer valid

Comments (Optional)

The details about why the certificate is being revoked. Be sure the comment length does not exceed the limitation from the CA. When accepting a revocation request, they may handle data outside their limits differently. For Entrust CA or EntrustPKI CA, the maximum character limit is 250.

Disable (Optional)

The setting to manage the Certificate object upon revocation:

  • true: Mark the certificate as disabled and no new certificate will be enrolled to replace the revoked one.
  • false: Allow a new certificate to be enrolled to replace the revoked one.

WorkToDoTimeout

(Optional) The maximum wait time for the certificate to revoke.

Overrides the Platforms tree setting for the Certificate API ToDo Timeout setting. The maximum number of seconds to wait for the ToDo operation to complete. The default is zero seconds with a maximum value of 120 seconds. For example:WorkToDoTimeout: 60. For more information, see Certificates API configuration.

Returns

Response description

Name

Description

HTTP 200

For valid requests made without WorkToDoTimeout, this call returns a HTTP 200 message and one of the following messages

  • Requested=true Success=true: Appears only when Certificates/Revoke API successfully initiated and revoked the certificate.

  • Revoked=true  Success=true and Warning: Appears only if the certificate was previously revoked.

HTTP 202

For requests that exceeded the WorkToDoTimeout, this call returns a HTTP 202 and the following data in the message body:

  • Revoked=falseSuccess=true

  • Error: The reason that certificate revocation failed. For example:

    • Revocation submission pending. WorkToDoTimeout exceeded.

HTTP 400

For invalid requests, this call returns a HTTP 400 BadRequest and the following data in the message body:

  • Error: The reason that certificate revocation failed. For example:

    • Certificate [ CertificateDN] does not exist.

    • Certificate [ CertificateDN] does not have a certificate to revoke.

    • Could not find a certificate object for the certificate with [thumbprint].
    • Could not find a certificate with the [thumbprint] thumbprint.
    • Failed to disable certificate.
    • Failed to request revocation.
    • Failed to revoke certificate no permission.
    • Missing Reason.
    • Need either CertificateDN or Thumbprint
    • (Warning) Revocation is completed. The certificate [ CertificateDN] revocation was requested by another request or process.
    • (Warning) Revocation is already completed. The [ CertificateDN] revocation was requested by another request or process.

HTTP 500

For server errors, this call returns a HTTP 500 and the following data in the message body:

  • Requested=true and Success=false: Appears when the certificate failed to revoke.
  • Error: The reason that certificate revocation failed. For example:
    • Could not find certificate [certificateDN]
    • Failed to retrieve certificate data from vault
    • Failed to initiate check for revocation status
    • Failed to request revocation, failed to read existing revocation state.
    • Revocation submission pending. WorkToDoTimeout exceeded
    • Revocation request failed, error: [revokeState.Error]
    • Revocation request failed, error: [error]

Example: Revoke a certificate

Request

POST https://tpp.venafi.example/vedsdk/Certificates/Revoke
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "Thumbprint":"1f3fa666194cdc5119d23cac192f3706b16a7977",
   "Reason":2,
   "Comments":"CA key was compromised."
}

Response

HTTP/1.1 200 OK
{
   "Requested":true,
   "Success":true
}