GET Certificates/{guid}/PreviousVersions

Returns details about previous versions of a certificate. A certificate version includes the X.509 certificate properties the CA used to sign the certificate during issuance or renewal.

Venafi Trust Protection Platform has updated certificate association data retrieval processes that use the UI and websdk APIs. The update optimizes the retrieval process by fetching data from new tables, where certificate strings such as common name, organization, organization unit, locality, state, country, and subject alternative names are normalized in a case-insensitive name table. However, the casing of the first added string pattern will determine the value returned for any related query. For instance, if a certificate is imported with 'CN=MyCommonName' and another certificate with 'CN=mycommonname', the returned value for any query will be 'CN=MyCommonName'.

The update also reduces database size by removing most certificate secret store associations from the store_associations table. As a result, the secret store association REST APIs for certificates have been officially deprecated and will no longer work for many certificate-specific associations. Instead, use the certificates REST APIs, which are documented in the Certificates API documentation. These changes impact users performing an upgrade, and it is essential to ensure that all certificates are managed correctly after the upgrade.

Requirements

  • Permissions: The caller must have View permission and Read permission.
  • Token scope:  Certificate

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

Parameter

{guid}

Specify this parameter as part of the URL. The GUID for the Certificate object. To get the GUID, call POST Config/DnToGuid. For example, {2b6b673f-2c55-46fc-935a-5836eae9b9db}.

ExcludeExpired

Specify this parameter as part of the URL.

  • true: Omit expired versions of the certificate.
  • false: Default. Include expired versions of the certificate.

ExcludeRevoked

Specify this parameter as part of the URL:

  • true: Omit revoked versions of the certificate.
  • false: Default. Include revoked versions of the certificate.

Returns

For invalid requests, Certificates/{guid}/PreviousVersions returns a HTTP 400 BadRequest for missing parameters or one of the following errors:

  • Certificate type verification failed. The object that corresponds with Guid [guid] is not a certificate.
  • Invalid certificate Guid. The value [guid] is null, empty, or in an invalid format.
  • Invalid permissions. You do not have permission to read the certificate with Guid [guid].
  • Object reading failed. The Certificate object with Guid [guid] does not exist or you do not have access to it.
  • Reading Secret Store failed. Reading Secret Store data returns error: [Secret Store error]

For valid requests, Certificates/Request returns a HTTP 200 message and the following data in the message body:

Response description

Name

Description

HTTP 200

For valid requests, this call returns a HTTP 200 message and the following data in the message body:

  • PreviousVersions: An array of version information about a certificate. Appears only if the GUID for the Certificate object has older versions.

    • CertificateDetails: A collection for each certificate version. The most current version appears first:

    • VaultId: The integer which uniquely identifies the Certificate Store location of the certificate. To download the certificate, use this value and GET Certificates/Retrieve/{vaultid} or POST Certificates/Retrieve/{vaultid}
  • Successtrue: The request was valid. If the GUID for the Certificate object has versions, PreviousVersions appears in the response.

HTTP 400

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

  • Error: [Error Message]
  • Successfalse: The request Error generates an HTTP 400 Bad Request and an error message.

Example: Get certificate history without older, revoked certificate versions

Request

GET https://tpp.venafi.example/vedsdk/certificates/
{25b11f10-1e2e-49fb-93b8-a781040f3bc7}/
PreviousVersions?ExcludeRevoked=true

Response

HTTP/1.1 200 OK
{
   "PreviousVersions":[
      {
         "CertificateDetails":{
            "C":"US",
            "CN":"test.vefunny.com",
            "Issuer":"CN=test.vefunny.com, O=Test Inc., OU=unit1, OU=unit2,  
               OU=unit3, L=SLC, S=Utah, C=US",
            "KeyAlgorithm":"RSA",
            "KeySize":2048,
            "KeyUsage":"None",
            "L":"SLC",
            "O":"Test Inc.",
            "OU":[
               "unit1",
               "unit2",
               "unit3"
            ],
            "PublicKeyHash":"D97D89164EE92AB6DBAC324F4A5B50B8CF54E62F",
            "S":"Utah",
            "SKIKeyIdentifier":"B18C44661C82ABE4A7BA6239062FA9D8886179E8",
            "Serial":"0AFADD0D417FC14A8C3FFED59D71E0D8",
            "SignatureAlgorithm":"sha256RSA",
            "SignatureAlgorithmOID":"1.2.840.113549.1.1.11",
            "StoreAdded":"2019-05-17T13:53:36.9458944Z",
            "Subject":"CN=test.vefunny.com, O=Test Inc., OU=unit1, OU=unit2, 
               OU=unit3, L=SLC, S=Utah, C=US",			
            "SubjectAltNameDNS":[
               "some.vefinny.com",
               "some2.vefunny.com"
            ],
            "SubjectAltNameEmail":[
               "test@mail.com",
               "test2@mail.com"
            ],
            "Thumbprint":"CAD753FA64D58AA411B02C6B21BE2EFAB6A0E1A4",
            "ValidFrom":"2019-05-17T13:53:36.0000000Z",
            "ValidTo":"2020-05-16T13:53:36.0000000Z"
         },
         "VaultId":399
      },
      {
         "CertificateDetails":{
            "C":"US",
            "CN":"test.vefunny.com",
            "Issuer":"CN=test.vefunny.com, O=Test Inc., L=SLC, S=Utah, C=US",
            "KeyAlgorithm":"RSA",
            "KeySize":2048,
            "KeyUsage":"None",
            "L":"SLC",
            "O":"Test Inc.",
            "PublicKeyHash":"62249CAAC9A567109A59932404C3E527E4510EA6",
            "S":"Utah",
            "SKIKeyIdentifier":"C936F63D20346791573AB49319992C42B2600803",
            "Serial":"1CF876ED6C4F0F48938179C229ACA354",
            "SignatureAlgorithm":"sha256RSA",
            "SignatureAlgorithmOID":"1.2.840.113549.1.1.11",
            "StoreAdded":"2019-05-16T14:50:30.8237628Z",
            "Subject":"CN=test.vefunny.com, O=Test Inc., L=SLC, S=Utah, C=US",
            "Thumbprint":"65276DAF482D6C52960DAF78D72B61B386A3FD7F",
            "ValidFrom":"2019-05-16T14:50:30.0000000Z",
            "ValidTo":"2020-05-15T14:50:30.0000000Z"
         },
         "VaultId":295
      },
      {
         "CertificateDetails":{
            "C":"US",
            "CN":"test.vefunny.com",
            "Issuer":"CN=test.vefunny.com, O=Test Inc., L=SLC, S=Utah, C=US",
            "KeyAlgorithm":"RSA",
            "KeySize":2048,
            "KeyUsage":"None",
            "L":"SLC",
            "O":"Test Inc.",
            "PublicKeyHash":"83585F97CFE8B961CF4CB6FB5825C71D54EEA52F",
            "S":"Utah",
            "SKIKeyIdentifier":"682D6D8AE5A9F07BB615BF8E47A52773D67DA397",
            "Serial":"5D91C062DD2A0B4A8BA5C9EC522F14FB",
            "SignatureAlgorithm":"sha256RSA",
            "SignatureAlgorithmOID":"1.2.840.113549.1.1.11",
            "StoreAdded":"2019-05-16T14:49:39.6373260Z",
            "Subject":"CN=test.vefunny.com, O=Test Inc., L=SLC, S=Utah, C=US",
            "Thumbprint":"343CB861352C27D434FFF8F6E61416CA512F9A92",
            "ValidFrom":"2019-05-16T14:49:39.0000000Z",
            "ValidTo":"2020-05-15T14:49:39.0000000Z"
         },
         "VaultId":292
      }
   ],
   "Success":true
}