POST Discovery/Import

Adds or updates a set of network certificates into a policy folder. To import a single certificate, call POST Certificates/Import instead.

This API can either run via your REST API call or run automatically. For more information, see Automatically calling Discovery/Import from Scanafi. Discovery/Import adds certificates to the Secret Store, and then associates each with a Certificate object. After a successful import, each Certificate, and all corresponding Device and Application objects appear in the policy folder.

If the certificate is already in the policy folder, this API call honors reconciliation logic that prevents creation of duplicate Certificate and Device objects. A warning occurs if the caller lacks permissions to another area of the policy folder that has the original certificate and it is not already accounted for by a Device and Application object.

Requirements

Permissions:
- Write permission and Create permission to the target zoneName.
- Recommended but not required. If other policy folders already have some of the certificates that you are importing, grant View permission with Associate permission. These permissions ensure that Device and Application objects in the policy folder can account for every certificate instance. If permission warnings occur, grant the caller these permissions to the certificate location in the policy folder. Then, rerun Discovery/Import.
Token scope: Certificate:Discover

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
endpoints	Case sensitive. A JSON array of certificates to import. Ignores all other parameters that are not listed below and any chain certificates. To get the data, see Manually calling Discovery/Import with Scanafi data. certificates: An array of network certificates to add to the policy folder: certificate: A Base-64 encoded certificate. fingerprint: A SHA-1 fingerprint, which is also known as a thumbprint. host: The host name. ip: The host IP address. port: The host port for Trust Protection Platform to run validation. protocols: An array of certificate fingerprints and valid protocol.
zoneName	Case sensitive. The destination policy folder or Policy Distinguished Name (DN) for newly discovered certificates and devices. If this API call imports more than one set of certificates, make sure to use a different folder.

Returns

The response includes information about HTTP 200 warnings or HTTP 400 Bad Request errors.

Response description
Name	Description
createdCertificates	The number of new certificates that were created in the zoneName. New certificates meet the following criteria: The SubjectDN value from an endpoints certificate does not match any other in the policy folder. The Key Usage, and Extended Key Usage (EKU) values from an endpoints certificate do not match any other in the policy folder. At least four Subject Alternate Name (SAN)s from an endpoints certificate do not match any other in the policy folder. Where do imported certificates appear? The new certificate appears in zoneName which is a policy folder . The progress of Certificate object creation appears in the event log. If there is an intermediate or corresponding root certificate, this information is ignored and not imported.
createdInstances	The number of new Basic application objects that are associated with imported certificates.
Error	The reason for failure. If Discovery/Import ran successfully, this field is omitted. Bad request. Check the error in the response for details. Bad request. There is no endpoint data. Incorrect request. Policy DN [zoneName parameter] is required. Missing Policy DN. PolicyDN: [PolicyDN] provided by zonename parameter does not exist or you do not have sufficient rights to the object. Permissions error. You do not have Create permissions to import certificates to the policy: [PolicyDN].
updatedCertificates	The number of certificates in endpoints that matched Certificate objects that are already in the policy folder. Additional information appears in the event log.
updatedInstances	The number of certificate installations that were already represented by Application objects in the policy folder. Additional information appears in the event log.
Warning	An array of any issues that occurred while processing the certificate. If there are no issues, the array is empty. Adding certificate to Secret Store error. Failed to add Certificate object with fingerprint [cert.GetCertHashString()] and DN [certificateDN] to Secret Store, Secret Store error: [X509CertificateStore.Error]. Adding certificate to Secret Store error. Failed to add certificate with fingerprint [Fingerprint] to Secret Store, Secret Store error: [EngineCertificateStore.Error]. Association error. Failed to associate Secret Store Id [VaultId] to Certificate object with fingerprint [Hash] and DN [CertificateDN], Config error: [Config.Error]. Certificate data parsing error. Failed to parse Certificate data with fingerprint [Fingerprint]. Create application error. Failed to create Application object with DN [currentDN], Config error: [Config.Error]. Create certificate error. Failed to create Certificate object with thumbprint [Hash] and DN [certificateDN],Config error: [Config.Error]. Create device error. Failed to create Device object with DN [currentDN], Config error: [Config.Error]. Permissions error. Certificate with fingerprint [hash] already exists but you do not have permission to associate a new instance with it. Set driver error. Failed to set a driver to Certificate object with thumbprint [Hash] and DN [certificateDN],Config error: [Config.Error].
zoneName	The destination policy folder or PolicyDN of newly discovered certificates.

Example: Load a policy folder with certificate data

Request

POST https://tpp.venafi.example/vedsdk/Discovery/Import
Authorization:Bearer 4MyGeneratedBearerTknz==   
{
   "zoneName":"\\VED\\Policy\\Certificates",
   "endpoints":[
      {
         "certificates":[
            {
               "certificate":"MIIEGwUA...",
               "fingerprint":"835bd89e5d4c9ad0e9679dd85eac798afbcfadb0"
            }
         ],
         "host":"192.168.7.52",
         "ip":"192.168.7.52",
         "port":443,
         "protocols":[
            {
               "certificates":[
                  "835bd89e5d4c9ad0e9679dd85eac798afbcfadb0"
               ],
               "protocol":"TLSv1.2"
            }
         ]
      }
   ]
}

Response

HTTP/1.1 200 OK
{
   "createdCertificates":1,
   "createdInstances":1,
   "updatedCertificates":0,
   "updatedInstances":0,
   "warnings":[

   ],
   "zoneName":"\\VED\\Policy\\Certificates"
}