GET Certificates

Returns certificate details and the total number of certificates that match the specified search filters. To get the X.509 certificate values to appear in the response, the caller must have Read permission to the Distinguished Name (DN). However, to return just the certificate and all object data, the caller is only required to have View permission.

GET Certificates only returns X.509 certificate values when there is an actual X.509 certificate in Secret Store for the certificate object. If you want the response to return just the total number of matches, use HEAD Certificates instead.

Requirements

  • Permissions: The caller must have Read permission and Private Key Read permission to the Certificate object.
  • 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

When adding query parameters, use the /? syntax. If you are not passing any parameters, make sure the URL ends with a trailing slash. Otherwise, some environments, such as cURL and PowerShell, return a HTTP 307 Temporary Redirect message.

Input parameters

Name

Description

[filters]

(Optional) One or more combinations of Certificates attribute filters and Certificates status filters. If there are no filters, the response includes every certificate.

Limit

(Optional) The maximum number of certificates to return. Specify any positive integer. However, if the number of certificates in the response is too large, timeouts may occur. Various factors, such as the load on the Web SDK server, network latency, and database performance help you determine the effective maximum number of certificates. The default is 100.

Offset

(Optional) The number of results to skip. To achieve paging, use in conjunction with the Limit parameter. For example, begin the result at page five and limit the output to ten pages: ?Limit=10&Offset=5.

OptionalFields

(Optional) Include one or more of the following certificate attributes in the return value:

  • Issuer: Show the distinguished name of the issuing certificate authority. Returns comma-separated values for Common Name (CN), Organizational Unit (OU), Organization (O), City/Locality (L), State/Province (ST), Country (C), and Domain Component (DC), as applicable.
  • KeyAlgorithm: Show the public key algorithm.
  • KeySize: Show the number of bytes allocated for the public key.
  • Subject: Show the distinguished name of the certificate. Returns comma-separated values for CN, OU, O, L, ST, C, and DC, as applicable.

For example, to add every optional field to the return value, specify ?OptionalFields=KeyAlgorithm,KeySize,Subject,Issuer.

Returns

Response description

Name

Description

HTTP 200

For valid requests, this call returns a HTTP 200 message. Returns certificates, which match the filters, from the Policy tree.

  • X-Record-Count: Appears in the response header. Indicates the total number of matching certificates.

  • Certificates: A summary for each matching certificate is returned. The summary includes:

    • CreatedOn: Date when the certificate object was created.
    • DN: The fully qualified distinguished name of the Certificate object in Trust Protection Platform.
    • Guid: The GUID for the Certificate object.
    • Name: The name of the Certificate object.
    • ParentDn: The full path to the parent of the object.
    • SchemaClass: The class name of the Certificate object: X.509 Certificate, X509 Code Signing Certificate,X.509 Device Certificate, X.509 Server Certificate, or X.509 User Certificate.

    • X509: Enrolled or issued certificate information:

      • CN: The Common name attribute of Subject DN.
      • Issuer: The CN ,O, L, S, and C values from the certificate. If OptionalFields is missing, Issuer is hidden.
      • KeyAlgorithm: The public key algorithm from the certificate. If OptionalFields is missing, KeyAlgorithm is hidden.
      • KeySize: The public key size. If OptionalFields is missing, KeySize, is hidden.
      • SANS: The Subject Alternate Names (SAN). An array of Domain Name System (DNS) and/or an array of IP addresses.
      • Serial: The certificate serial number.
      • Subject: Any C, CN, L, O, OU, and Subject DN that applies to the certificate. If OptionalFields is missing, Subject is hidden.
      • Thumbprint: The SHA1 thumbprint (hash) of the certificate.
      • ValidFrom: The date when the certificate was issued.

      • ValidTo: The date when the certificate expires.

    • _links: An array of Hypertext Application Language (HAL)-based links to retrieve the next and previous page of results via the certificates API if paging is in effect.
    • DateRange: The range of certificates returned in the response. For example, 1 - 25 means the first certificate out of a total of 25 results.
    • TotalCount: Appears only when one or more records appear in the response. The total number of matching results. The value may be larger than the number of returned results if paging is in effect.

HTTP 307

If the method is missing a slash (/) at the end of the URL or between the query parameters, this message appears: There is no operation listening for [Web SDK method], but there is an operation listening for [Web SDK method/], so you are being redirected there.

HTTP 400 on Error

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

  • ErrorDetails: Returns an error message for bad parameters, data, or syntax.

      • Invalid Boolean value. The value [value] for the parameter [parameter] contained spaces, a non-numeric, or a number other than zero or one.
      • Invalid Certificate type. The value [value] for the parameter [parameter] failed to match any required value: Device, User, or Server.
      • Invalid DateTime format. The value [value] for the parameter [parameter] requires a date and time in the IS0 8601 format.
      • Invalid Management type. The value [value] for the parameter [parameter] failed to match any required value: Monitoring, Enrollment, Provisioning, or Unassigned.
      • Invalid numeric format. The value [value] for the parameter [parameter] cannot be null, non-numeric, or contain white spaces.

      • Invalid TrustNetReputation value. The value [value] for the parameter [parameter] is invalid. Only numbers between 0 and 100 are allowed.

Example 1: Search certificates by parent folder

Request for Example 1

GET https://test.venafi.example/vedsdk/certificates/?parentdnrecursive=%5CVED%5CPolicy&limit=2&offset=0 
Authorization:Bearer 4MyGeneratedBearerTknz==

Response for Example 1

HTTP/1.1 200 OK
{
   "Certificates":[
      {
         "CreatedOn":"2018-07-16T16:35:35.9468326Z",
         "DN":"\\VED\\Policy\\Venafi Operational Certificates\\WIN-MLK71Q10559",
         "Guid":"{2a25573b-745c-4018-806a-e5c73f424675}",
         "Name":"WIN-MLK71Q10559",
         "ParentDn":"\\VED\\Policy\\Venafi Operational Certificates",
         "SchemaClass":"X509 Server Certificate",
         "X509":{
            "CN":"WIN-MLK71Q10559",
            "SANS":{
               "DNS":[
                  "WIN-MLK71Q10559"
               ]
            },
            "Serial":"14C1713280EB5F429234DC374310B061",
            "Thumbprint":"6323B71D1C5E38F211EEB34EDC8F9D981F8C835A",
            "ValidFrom":"2018-07-16T16:35:36.0000000Z",
            "ValidTo":"2019-07-16T16:35:36.0000000Z"
         },
         "_links":[
            {
               "Details":"/vedsdk/certificates/%7b2a25573b-745c-4018-806a-e5c73f424675%7d"
            }
         ]
      }
   ],
   "DataRange":"Certificates 1 - 1",
   "TotalCount":1
}

Example 2: Return additional X.509 information

This example returns additional information about the KeyAlgorithm, KeySize, Subject, and Issuer.

Request for Example 2

GET https://test.venafi.example/vedsdk/certificates/
?optionalFields=keyalgorithm,keysize,subject,issuer 

Authorization:Bearer 4MyGeneratedBearerTknz==

Response for Example 2

HTTP/1.1 200 OK 
{
   "Certificates":[
      {
         "CreatedOn":"2018-12-17T17:00:13.3414183Z",
         "DN":"\\VED\\Policy\\Venafi Operational Certificates\\WIN-MLK71Q10559",
         "Guid":"{06f30e95-a508-4f2d-8702-23d431bc0ebd}",
         "Name":"WIN-MLK71Q10559",
         "ParentDn":"\\VED\\Policy\\Venafi Operational Certificates",
         "SchemaClass":"X509 Server Certificate",
         "X509":{
            "CN":"WIN-MLK71Q10559",
            "Issuer":"CN=WIN-MLK71Q10559, OU=Venafi Operational Certificate",
            "KeyAlgorithm":"RSA",
            "KeySize":2048,
            "SANS":{
               "DNS":[
                  "WIN-MLK71Q10559"
               ]
            },
            "Serial":"2A87CC5726537F45BCA3DC9C23453614",
            "Subject":"CN=WIN-MLK71Q10559, OU=Venafi Operational Certificate",
            "Thumbprint":"5025AE1D64A16FA8C128907E2A85923774041E7F",
            "ValidFrom":"2018-12-17T17:00:11.0000000Z",
            "ValidTo":"2019-12-17T17:00:11.0000000Z"
         },
         "_links":[
            {
               "Details":"/vedsdk/certificates/%7b06f30e95-a508-4f2d-8702-23d431bc0ebd%7d"
            }
         ]
      }
   ],
   "DataRange":"Certificates 1 - 1",
   "TotalCount":1
}

Example 3: Find certificates expiring on a specific day

This example uses ValidToGreaterand ValidToLess to restrict the results to certificates expiring over a 24 hour period.

Request for Example 3

GET https://test.venafi.example/vedsdk/certificates/?
ValidToGreater=2016-11-12T00:00:00.0000000Z&
ValidToLess=2016-11-13T00:00:00.0000000Z

Authorization:Bearer 4MyGeneratedBearerTknz==

Response for Example 3

HTTP/1.1 200 OK
{  
   "Certificates":[  
      {  
         "CreatedOn":"2015-11-11T17:44:18.1457594Z",
         "DN":"\\VED\\Policy\\North America\\Venafi.com",
         "Guid":"{ad568169-bf93-458b-9457-31dfa32b6980}",
         "Name":"Venafi.com",
         "ParentDn":"\\VED\\Policy\\North America",
         "SchemaClass":"X509 Server Certificate",
         "X509":{  
            "CN":"ASU-VRK71Q10559",
            "SANS":{  
               "DNS":[  
                  "ASU-VRK71Q10559"
               ]
            },
            "Serial":"14C1713280EB5F429234DC374310B061",
            "Thumbprint":"6323B71D1C5E38F211EEB34EDC8F9D981F8C835A",
            "ValidFrom":"2017-08-16T19:21:44.0670287Z",
            "ValidTo":"2019-07-16T16:35:36.0000000Z"
         },
         "_links":[  
            {  
               "Details":"/vedsdk/certificates/%7bat568169-bf93-458b-9457-31dfa3b6980%7d"
            }
         ]
      }
   ],
   "DataRange":"Certificates 1 - 1",
   "TotalCount":1
}

Example 4: Multi-parameter query

The following query searches for certificates signing with md5RSA or sha1RSA, expiring after January 16, 2016, and that are contained within a particular folder (and its subfolders). It also specifies how many results should be returned at once and an offset. The response includes HAL-based links for the previous and next pages, which makes it easy to programmatically navigate to those pages.

Request for Example 4

GET https://test.venafi.example/vedsdk/certificates/?
SignatureAlgorithm=md5RSA,sha1RSA&KeySizeLess=1025&
ValidToGreater=2016-01-16T00:00:00.000000Z&
parentdnrecursive=%5CVED%5CPolicy%5CCerts&
limit=1&offset=1 

Authorization:Bearer 4MyGeneratedBearerTknz==

Response for Example 4

HTTP/1.1 200 OK
{
   "Certificates":[
      {
         "CreatedOn":"2015-10-24T00:51:38.7474177Z",
         "DN":"\\VED\\Policy\\Certs\\eng.venafi.com",
         "Guid":"{db32dd87-1a8e-49bf-9058-bc71f5de2ad4}",
         "Name":"eng.venafi.com",
         "ParentDn":"\\VED\\Policy\\Certs",
         "SchemaClass":"X509 Device Certificate",
         "X509":{...},
         "_links":[
            {
               "Details":"/vedsdk/certificates/%7bdb32dd87-1a8e-49bf-9058-bc71f5de2ad4%7d"
            }
         ]
      }
   ],
   "DataRange":"Certificates 2 - 2",
   "TotalCount":393,
   "_links":[
      {
         "Next":"/vedsdk/certificates?SignatureAlgorithm=md5RSA%2csha1RSA&
		KeySizeLess=1025&
		ValidToGreater=2016-01-16T00%3a00%3a00.000000Z&
		parentdnrecursive=%5cVED%5cPolicy%5cCerts&offset=2&limit=1",
         "Previous":"/vedsdk/certificates?SignatureAlgorithm=md5RSA%2csha1RSA&
		KeySizeLess=1025&	
		ValidToGreater=2016-01-16T00%3a00%3a00.000000Z&		
		parentdnrecursive=%5cVED%5cPolicy%5cCerts&offset=0&
		limit=1"		 
      }
   ]
}