POST Certificates/Push

Provisions the same certificate and private key to one or more devices or servers. The certificate must be associated with one or more Application objects. If the certificate and private key already exist on the target server or device, the Push operation replaces the existing certificate and private key.

DID YOU KNOW?  Certificates/Push operates in the same way as the Push buttonPush button on the Application object Settings tab.

Prerequisites

The Certificate DN, also known as a Certificate object, requires:

  • A device or server certificate with a Management Type of Provisioning.
  • A private key.
  • Not in an error or processing state. The Certificate DN has a stage of 0 or 800.

The Application DN, also known as an Application object, requires:

  • Association with a certificate. To set the Associated Applications, use the UI or call POST Certificates/Associate.
  • An enabled status. For example, the Processing Disabled checkbox is cleared.
  • Not in an error or processing state. The Application DN has a stage of 0 or 1200.

Requirements

  • Permissions:  The caller must have:
    • Read permission and Write permission to the Certificate object.
    • Write permission and Associate permission to relevant Application objects.
  • Token scope:  Certificate:Manage

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

  • To provision via a set of Application DNs that are associated with a certificate, specify ApplicationDN and set PushToAll to false.
  • To provision via all Application DNs that are associated with a certificate, omit ApplicationDN and set PushToAll to true.
Input parameters

Name

Description

ApplicationDN

(Optional) If you want to use every Application DN that is associated with the certificate, omit this value. An array of one or more Application objects, specified by their distinguished names, that uniquely identify them in the Venafi platform. Each Application DN is associated with the certificate.

CertificateDN

The Distinguished Name (DN) of the certificate.

PushToAll

Specify how to push provision:

  • true: Provision the certificate via all associated Application DNs. Be sure to omit ApplicationDN.
  • false: Default. Provision the certificate only via ApplicationDN.

Returns

Response description

Name

Description

HTTP 200

For valid requests, this call returns a HTTP 200 message and true when provisioning initiates.

HTTP 400

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

Error: Returns an error message for bad parameters, data, or syntax:

  • Access error. You do not have access to orphan Device [0], device].
  • Application [ApplicationDN] is associated with a different certificate [values].
  • Application class error. The Application [ApplicationDN] has type Application Base and does not support provisioning.
  • Application disabled. The Application [ApplicationDN] processing is disabled.
  • Application error. The Application [ApplicationDN] is not associated with the certificate.
  • Application in error. The Application [ApplicationDN] is in error state.
  • Application object error. [TypeName] is not an Application object of DN [ApplicationDN].
  • Application object error. Application [ApplicationDN] is in an error state.
  • Application object error. Failed to retrieve Application object [ApplicationDN].
  • Application requires private key. The Application [ApplicationDN] requires a private key for associated certificate.
  • Application stage error. The Application [ApplicationDN] is in stage [stage].
  • Application type error. Application [ApplicationDN] has type Application Base and does not support provisioning.
  • Certificate is disabled. Certificate [CertificateDN] processing is disabled.
  • Certificate is in error. Certificate [CertificateDN] is in an error state.
  • Certificate object error. [Certificate] is not a Certificate object of DN [DN].
  • Certificate wrong type. The Certificate object of DN [DN] is a [Certificate Class Name] and does not support provisioning.
  • Certificate wrong type. The Certificate object of DN [DN} is an X509 Code Signing Certificate and does not support provisioning.
  • Certificate wrong type. The Certificate object of DN [DN} is an X509 User Certificate and does not support provisioning.
  • Class read error. Failed to retrieve the Certificate object.
  • Config error. Failed to clear certificate attribute for Application [ApplicationDN]. [Error]
  • Config error. Failed to update Certificate [CertificateDN] consumers. [Error]
  • Could not find [CertificateDN].
  • Dissociate error. Certificate [CertificateDN] is not currently associated with the application [ApplicationDN].
  • Invalid Application DN. Application DN is null or contains white spaces for [ApplicationDN].
  • Invalid Application DN. Application object with Distinguished Name [ApplicationDN] does not exist or you do not have access to it.
  • Invalid certificate data. Certificate object [CertificateDN] does not contain certificate data.
  • Invalid Certificate DN. Certificate Distinguished Name [0] does not exist or you do not have access to it.
  • Invalid Certificate stage. Certificate [CertificateDN] stage is [stage]. The stage must be empty or have a value of 800.
  • Invalid request. Application DN [ApplicationDN] data is missing.
  • Invalid request. Certificate DN [CertificateDN] is missing.
  • Permissions error. You do not have Delete permission to the orphan Application [ApplicationDN].
  • Permissions error. You do not have Delete permission to the orphan Device [Device].
  • Permissions error. You do not have Read permission to the Application [ApplicationDN].
  • Permissions error. You do not have Write or Associate permission to the Application [ApplicationDN].
  • Permissions error. You do not have Write permission to the Certificate DN [CertificateDN].
  • PolicyDN error. [policy] does not exist or you do not have sufficient rights to the object.
  • Provisioning error. Failed to start provisioning ToDo for Application [ApplicationDN].
  • Reconciliation error. The certificate already exists at Certificate DN [policy].

  • There are no applications to push. Check warning for details.
  • WorkToDo is running on another process. Certificate [CertificateDN] failed to push to a new Application object.

Example: Push Provision one certificate to set of Application objects

Request

POST https://tpp.venafi.example/vedsdk/Certificates/Push
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "CertificateDN":"\\VED\\Policy\\Certificates\\Lab4DeviceCert",
   "ApplicationDN":[
      "\\VED\\Policy\\Devices\\Cisco Router ISR 1900\\BlueCoatAO",
      "\\VED\\Policy\\Devices\\WebServer91\\ApacheAO"
   ],
   "PushToAll":"false"
}

Response

HTTP/1.1 200 OK
{
   "Success":true
}