POST Certificates/Import

Adds or replaces one Privacy-enhanced Electronic Mail (PEM) certificate in the Policy tree based on the reconcile option. To import a set of certificates, use POST Discovery/Import instead.

The Certificates/Import API call can include an optional private key or a PKCS#12 keystore with both the certificate and private key as a Base64 encoded blob. To replace an existing certificate, see How to call Certicates/Import to replace keys and certificates.

After a successful import, the certificate appears in the Policy folder. For more information, see How imported values map to a X.509 certificate. If the Certificates Type was not previously set, Certificates/Import automatically sets the value. For more information, see How Certificates/Import assigns Certificate Type.

Requirements

Permissions: The caller must have Master Admin permission or the caller must have View permission, Read permission, Write permission, Create permission, and Private Key Write permission to the Certificate object.
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
CASpecificAttributes	(Optional) An array of name/value pairs providing any CA attributes to store with the Certificate object, and then submit to the CA during enrollment. For more information, see X509 Certificate CA Specific Attributes.
CertificateData	One certificate that requires importing into Trust Protection Platform: If the BEGIN/END header or footer is missing, the data is assumed to be Base 64 encoded in the PKCS#12 format. For Base 64 encoded certificates, characters, such as spaces and new line escape characters (/n), are optional. White space characters are removed before any attempt is made to decode the certificate.
ObjectName	(Optional) The friendly name for the Certificate object in Trust Protection Platform.
Password	Required if the certificate has a private key. The password works in conjunction with PrivateKeyData.
PolicyDN	The Distinguished Name (DN) of the folder that will hold the certificate.
PrivateKeyData	(Optional) The private key data. Requires a Password. For a PEM certificate, the private key is in either the RSA or PKCS#8 format. If the CertificateData field contains a PKCS#12 formatted certificate, this parameter is ignored because only one private key is allowed.
Reconcile	The setting to control certificate and corresponding private key replacement: false: Default. Import and replace. Import the certificate into the PolicyDN regardless of whether a past, future, or same version of the certificate exists in Trust Protection Platform. true: Import, but use newest. Only import the certificate into the PolicyDN when no Certificate object exists with a past, present, or current version of the imported certificate. If a match is found between the Certificate object and imported certificate, activate the certificate with the most current 'Valid From' date. Archive the unused certificate, even if it is the imported certificate, to the History tab.

Returns

For invalid requests, Certificates/Import returns a HTTP 400 Bad Request and an error message. For more information, see POST Certificates/Import error messages. For valid requests, this API 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: CertificateDN: A unique Certificate Distinguished Name (DN), also known as Certificate object name: If the request included the ObjectName, the CertficateDN includes both the PolicyDN and the certificate ObjectName. If the request omitted the ObjectName, the CertficateDN uses the certificate Common Name (CN). The derived certificate object name references an existing object (of any class). If another certificate has the same CN, a dash (-) integer appends to the CertificateDN. For example, test.venafi.example - 3. If the request omitted the ObjectName and the CN is also missing, the CertificateDN uses the first Domain Name System (DNS) Subject Alternative Name (SAN). If the requested omitted ObjectName and the both CN, and DNS SAN are also missing, the CertificateDN is the serial number. CertificateVaultId: The ID of the vault that holds the certificate. Guid: A GUID that uniquely identifies the certificate. PrivateKeyVaultId: If the CertificateDN omitted private key information, this field is absent in the return value. The integer which uniquely identifies the Secret Store vault location for the private key.
HTTP 400	For invalid requests, this call returns a HTTP 400 BadRequest and the following data in the message body: Error: [Error Message]

Example: Import and replace an existing certificate

Request

POST https://tpp.venafi.example/vedsdk/Certificates/Import
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "PolicyDN":"\\VED\\Policy\\Import",
   "ObjectName":"test.venafi.example",
   "CASpecificAttributes":[
      {
         "Name":"Transaction Id",
         "Value":"A1B2C3D4E5F6"
      },
      {
         "Name":"Internet EMail Address",
         "Value":"email@yourcompany.com"
      }
   ],
   "Reconcile":"true",
   "CertificateData":"-----BEGIN CERTIFICATE"-----\nMIIEO
    -----END CERTIFICATE-----\n",
{
   "PrivateKeyData":"-----BEGIN RSA PRIVATE KEY-----\nMIIEp
    -----RSA PRIVATE KEY-----\n"
}

}

Response

HTTP/1.1 200 OK
{
   "CertificateDN": "\\VED\\Policy\\Certificates\\test.venafi.example1.com",
   "CertificateVaultId":60736,
   "Guid":"{a5f4d529-9f37-47d4-ac34-7b55487c11d4}",
   "PrivateKeyVaultId":60737
}