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
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.
|
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.
Name |
Description |
---|---|
createdCertificates |
The number of new certificates that were created in the zoneName. New certificates meet the following criteria:
Where do imported certificates appear?
|
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.
|
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.
|
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" }