POST Certificates/Associate

Allows one or more Application objects of devices to use an existing certificate. Optionally, Certificates/Associate can launch certificate provisioning. After the association between the Certificate and Application object is complete:

  • The certificate with a 'Provisioning' Management type is ready to install on a device. If PushToNew is true and the certificate is currently in a state that allows provisioning (not disabled, not in error, nor already in process), provisioning to the newly associated device begins.

  • Additional information appears on the Associations tab of the Application object.

Requirements

  • Permissions:  The caller must have Write permission to the Certificate Distinguished Name (Certificate DN) object. The caller must also have Write permission or Associate permission and Delete 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

Input parameters

Name

Description
ApplicationDN An array of one or more Application objects, specified by their distinguished names, that uniquely identify them in the Venafi platform.
CertificateDN

The Distinguished Name (DN) of the certificate.

PushToNew

An additional provision action for the certificate:

  • true: Provision the certificate after associating it to the Application objects in ApplicationDN.
  • false: Default. Do not provision the certificate at this time.

Returns

Response description

Name

Description

HTTP 200

For valid requests, this call returns a HTTP 200 message and the following data in the message body:

  • Success: true when the set of certificates successfully associate with the Application DN, otherwise false.

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:

    • Application object error. [Config object 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].

    • Associate error. Application [ ApplicationDN] is associated with a different certificate [ CertificateDN].

    • Certificate is disabled. Certificate [CertificateDN] processing is disabled.

    • Certificate is in error. Certificate [CertificateDN] is in an error state.

    • Certificate object error. [ConfigObject TypeName] is not a Certificate object of DN [ CertificateDN].

    • Class read error. Failed to retrieve the Certificate object.

    • Failed to add work for Application [ApplicationDN]. Push will not occur. Failure details: [ErrorMessage] Result Code: [ Certificates WorkToDo result codes ].

    • Failed to add work for Certificate [CertificateDN]. Push will not occur. Failure details: [ErrorMessage] Result Code: [ Certificates WorkToDo result codes ].

    • Invalid Application DN. The Application DN is null or contains white spaces for [ ApplicationDN].

    • Invalid Application DN. The 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 [CertificateDN] does not exist or you do not have access to it.

      Invalid certificate data. Certificate object [CertificateDN] does not contain certificate data.

    • Invalid Management Type. Certificate [CertificateDN] Management Type is [ManagementType.PushToNew requires a 'Provisioning' Management Type.

    • 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 Write or Associate permission to the Application [ ApplicationDN].

    • PushtoNew failed. Application [ApplicationDN] is disabled.

    • WorktoDo already is running on another process. Certificate [CertificateDN] failed to push to a new Application object.

  • Success: false.

Example: Associate an application with a certificate

Request

POST https://tpp.venafi.example/vedsdk/Certificates/Associate
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "CertificateDN":"\\VED\\Policy\\CertificateSet\\Cert75G-Lab04",
   "ApplicationDN":[
      "\\VED\\Policy\\CertificateSet\\HSM95\\F5 LTM Advanced"
   ],
   "PushToNew":"true"
}

Response

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