Searching for certificates

To retrieve information about your certifiates, use one of the following API functions. You can only search for certificates that are associated with your company account:

I want information about

Use this search API function

Discovered certificates that originate from external domains or from internal networks

certificatesearch

Discovered certificates that originate from external domains

managedcertificatesearch

Certificate instance, installation, or provision details for discovered certificates

certificateinstancesearch

To search for certificates

  1. If you have not already done so, obtain an API key.

  2. Use the certificatesearch, certificateinstancesearch, or managedcertificatesearch function. For additional help, use the parameter descriptions from our documentation. For example:

    POST https://api.venafi.cloud/v1/certificatesearch
    tppl-api-key: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  3. In the JSON body, use the expression to specify your search criteria:

    expression

    The operands parameter that contains an array of search criteria. For each set, specify these values:

    • field: A certificate field name. For example signatureHashAlgorithm or certificateType. Use the appropriate search parameters.
    • operator: One of the following condition operators EQ, LT, LTE, GT, GTE, IN, MATCH, FIND, MOD. Use the appropriate search operators.
    • value: A single search value. -OR-
    • values: Multiple search values in an array. Use in conjunction with the IN operator. Specify a comma separated list of strings in quotes or integers without quotes.

    joinexpression

    The operator: that allows AND or NOT filtering.

    ordering (Optional)

    The orders parameter that contains an array of sort parameters. Specify these values:

    • direction: A sort order ASC or DESC (ascending or descending).
    • field: The sort field name.

    paging (Optional)

    The parameters that dictate the size of the data set to returned When working with a large set of results, the REST API supports paging through the result set. For example, if the query returns 100 results, you can specify pageSize of ‘10’ and 1,2…10 to iterate through all 10 result pages. Specify these values:

    • pageNumber: The page from the result set to return.
    • pageSize: The maximum number of records to return in the response.

    Example JSON body:

    {
      "expression": {
        "operands": [
          {
            "field": "selfSigned",
            "operator": "EQ",
            "value": "false"
          }
        ]
      },
      "ordering": {
        "orders": [
          {
            "direction": "ASC",
            "field": "subjectCN"
          },
          {
            "direction": "DESC",
            "field": "keyStrength"
          }
        ]
      },
      "paging": {
        "pageNumber": 1,
        "pageSize": 10
      }
    }					

    Example response

    HTTP 1.1 OK
    {
      "count": 1,
      "certificates": [
        {
          "id": "80c30620-2faa-11e7-bbb8-d7e9aadda3cb",
          "companyId": "9c731a20-2f8e-11e7-be41-1507c9a9e451",
          "fingerprint": "5DE3432B00F9CE2399AB7163676520C6774EA622",
          "certificateSource": "TRUSTNET_SCAN",
          "certificateStatuses": [
            "NONE"
          ],
          "certificateType": "END_ENTITY",
          "creationDate": "2017-05-03T02:45:00.930+0000",
          "modificationDate": "2017-05-03T02:45:00.930+0000",
          "totalInstanceCount": 1,
          "validityStart": "2017-01-25T17:01:32.000+0000",
          "validityEnd": "2018-01-25T17:01:32.000+0000",
          "validityPeriodDays": 365,
          "validityPeriodRange": "GT_30_DAYS_LTE_2_YEARS",
          "selfSigned": false,
          "signatureAlgorithm": "SHA256_WITH_RSA_ENCRYPTION",
          "signatureHashAlgorithm": "SHA256",
          "encryptionType": "RSA",
          "keyStrength": 2048,
          "publicKeyHash": "F7B78F7471AB2EED777CD488377E32A90B9DB530",
          "subjectKeyIdentifierHash": 
             "8C8ADFDDDB849486A8E003A270D0785918E79EE2",
          "authorityKeyIdentifierHash": 
             "CC338779405F8AD8846161E347F5EADDDC9FC2E1",
          "serialNumber": "1F3EBEFB0001000080C6",
          "subjectCN": [
            "iisUSPS13.lab.venafi.com"
          ],
          "subjectST": "UT",
          "subjectL": "Salt Lake City",
          "subjectC": "US",
          "subjectAlternativeNamesByType": {
            "otherName": [],
            "rfc822Name": [],
            "dNSName": [],
            "x400Address": [],
            "directoryName": [],
            "ediPartyName": [],
            "uniformResourceIdentifier": [],
            "iPAddress": [],
            "registeredID": []
          },
          "issuerCN": [
            "traininglab-Root-CA"
          ],
          "keyUsage": [
            "digitalSignature",
            "keyEncipherment"
          ],
          "ocspNoCheck": false,
          "compliance": {
            "score": 0.7691358024691359
          },	
          "instances": [
            {
              "id": "80c61360-2faa-11e7-bbb8-d7e9aadda3cb",
              "certificateId": "80c30620-2faa-11e7-bbb8-d7e9aadda3cb",
              "companyId": "9c731a20-2f8e-11e7-be41-1507c9a9e451",
              "zoneId": "9c7dc881-2f8e-11e7-be41-1507c9a9e451",
              "fingerprint": "5DE3432B00F9CE2399AB7163676520C6774EA622",
              "certificateSource": "TRUSTNET_SCAN",
              "certificateStatuses": [
                "NONE"
              ],
              "creationDate": "2017-05-03T02:45:00.950+0000",
              "modificationDate": "2017-05-03T02:45:00.950+0000",
              "ipAddress": "127.0.0.1",
              "ipAddressAsLong": 2927720739,
              "hostname": " ",
              "port": 443,
              "sslProtocols": [
                "SSLv2",
                "SSLv3",
                "TLSv1"
              ],
              "cipherSuites": [
                "TLS_RSA_WITH_3DES_EDE_CBC_SHA",
                "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA",
                "TLS_RSA_WITH_AES_128_CBC_SHA",
                "TLS_RSA_WITH_RC4_128_SHA",
                "TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA",
                "TLS_RSA_WITH_RC4_128_MD5",
                "TLS_RSA_WITH_AES_256_CBC_SHA",
                "PCT_SSL_CERT_TYPE"
              ],
              "heartbleedVulnerable": false,
              "logjamVulnerable": false,
              "poodleVulnerable": true,
              "poodleTlsVulnerable": false,
              "hstsEnabled": false,
              "alpnEnabled": false,
              "forwardSecrecyEnabled": true,
              "npnEnabled": false,
              "ocspStaplingEnabled": false,
              "renegotiationEnabled": false,
              "secureRenegotiationSupported": true,
              "tnLastUpdated": "2017-05-03T02:43:14.171+0000",
              "lastScanDate": "2017-03-05T11:00:00.000+0000",
              "sslProtocolsSecurityStatus": "DEPRECATED",
              "cipherSuitesSecurityStatus": "DEPRECATED",
              "compliance": {
                "score": 0
              }
            }
          ]
        }
      ]
    }