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: A collection of certificate Information AIAKeyIdentifier: Available only when the certificate was issued by a well-configured CA. The Authority Key Identifier, which is used when building the chain, should always match the Subject Key Identifier of the issuing CA's certificate. C: The country. CDPURI: The CRL Distribution Point (CDP) URI for certificate revocation lists (CRL). CN: The Common name attribute of Subject Distinguished Name (DN). EllipticCurve: Only available for ECC certificates. The key strength for encrypting public keys with the Elliptic Curve Cryptography (ECC) algorithm. EnhancedKeyUsage: The PKI Server Authentication object identifier (OID). Issuer: The CN, O, L, S, and C values from the certificate request. KeyAlgorithm: The algorithm for the public key. KeySize: Only available for RSA certificates. The bit size of the public key. KeyUsage: A list of Key Usage extension values that describe the purpose of the public key. L: The location. The value originates from the City field value from the certificate request. O: The Organization value from the certificate request. OU: An array of Organization Units or names. PublicKeyHash: The public key hash string. Available only when the certificate has a private key. RevocationDate: Available only when the certificate is revoked. The date the certificate will no longer be valid. RevocationStatus: Available only when a revocation request occurred for the certificate or when the certificate is already revoked. The status of a revoked certificate: Complete, Confirmed, Pending or Failed. A Failed status occurs as a result of errors or a rejection of a workflow ticket. S: The geographical State value from the certificate request. SKIKeyIdentifier: The generated Subject Key Identifier (SKI) Serial: The unique serial number that CA assigned to the certificate. SignatureAlgorithm: The signature algorithm for signing the certificate. SignatureAlgorithmOID: The Signature Object ID for signing the certificate. StoreAdded: The Date Time stamp when the private key was added to the store. Subject: The CN, O, L, S, and C values from the certificate request. SubjectAltNameDNS: An array of Domain Name System (DNS) SANs. SubjectAltNameEmail: An array of Email SANs. Based on RFC 822. SubjectAltNameIPAddress: An array of IP Address SANs. SubjectAltNameOtherNameUPN: An array of User Principal Name (UPN) SANs. SubjectAltNameURI: An array of Uniform Resource Indicator (URI) SANs. Template Major Version: Only available if there is a certificate template major version. Template Minor Version: Only available if there is a certificate template version. Template Name: Only available if a friendly template name that issued a certificate. Template Oid: Only available if the certificate originated from a certificate template. The object ID (OID) of the template that issued a certificate. Thumbprint: The SHA1 thumbprint hash of the certificate. ValidFrom: The date when the certificate was issued. ValidTo: The date when the certificate expires. 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} Success: true: 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] Success: false: 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
}