POST Certificates/Reset

Resets the state of a certificate and its associated applications. Certificates/Reset can also reset private key mismatch errors.

Certificates/Reset performs the following actions

  • Clears the Stage, Work To Do, Provisioning Work To Do, and In Error attribute of a certificate. Restores the certificate and its associated applications to OK status via the certificate Status attribute. For more information, see Parent class—X509 Certificate Base.

  • Corrects private key mismatch errors. If the private key is owned by the Certificate object, the private key resets to the active certificate. The private key, which is referenced by the Private Key Vault Id attribute, resets to match the active certificate that is referenced by the Certificate Vault Id attribute.

    If the private key is either missing in SecretStore or not owned by the Certificate object, the Private Key Vault Id attribute clears to resolve the mismatch.

  • Optionally, restarts the certificate after successful completion of the reset tasks. The certificate status is set to Work To Do=1 for certificate renewal. This action is equivalent to the Restart button in the UI.

  • Clears the revocation state, regardless of whether the certificate is revoked or in an error state.

Requirements

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

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

Input parameters

Name

Description
CertificateDN

The Distinguished Name (DN) of the certificate.

Restart

(Optional) The action to perform after certificate reset completes:

  • true = After reset completes, restart the certificate lifecycle.
  • false = After reset completes, skip the restart.

WorkToDoTimeout

(Optional) The maximum wait time to reset the certificate.

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, this call returns a HTTP 200 message and the following data in the message body:

  • PrivateKeyMismatchResetCompleted:true: The private key mismatch issue is resolved. The active private key now matches the active certificate. If the private key was missing from the SecretStore or the Certificate object had not own the private key, the updated Certificate object currently has no active private key.

  • ProcessingResetCompleted:true: The processing stage, regardless of its previous status is now set to OK for the certificate and its associated application. The error attribute (if any), is now cleared. Any pending workflow tickets have been deleted.

  • RestartCompleted:true: The reset tasks completed successfully. Certificate renewal initiated.

  • RevocationResetCompleted:true: The revocation status of the certificate is now clear.

HTTP 400

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

Error: [Error Message]

  • Access error. Your don't have write permissions for certificate [ CertificateDN].
  • CertificateDN error. CertificateDN: [ CertificateDN] does not exist or you do not have sufficient rights to the object.
  • Failed to lock certificate. The reset failed because the certificate is currently in use by another process. Please try again later.
  • Invalid CertificateDN format. The Certificate DN contained null or white spaces for [ CertificateDN]. This error occurs when the required field CertificateDN is missing from the request.
  • Management Type error. The reset failed because the certificate Management Type is Unassigned.
  • Reset is not completed. No reset is required for the certificate.

Example: Reset a certificate that had a private key mismatch

Request

POST https://tpp.venafi.example/vedsdk/Certificates/Reset
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "CertificateDN":"\\VED\\Policy\\MyPolicy\\ResetKeyCertMismatch",
   "Restart":"true"
}

Response

HTTP/1.1 200 OK
{
   "PrivateKeyMismatchResetCompleted": true,
   "ProcessingResetCompleted": true,
   "RestartCompleted": true,
   "RevocationResetCompleted": true
}