PUT Certificates/{guid}

Sets or clears one or more Config attributes of a X.509 certificate. For example, PUT Certificates/{guid} can use the special Disabled attribute to retire or reactivate a certificate.

If a policy is in effect for the attribute:

  • Trust Protection Platform enforces the policy. To find policy information, call POST Config/FindPolicy.
  • A warning occurs.
  • The attribute remains unchanged.

Requirements

  • Permissions:  The caller must have View permission and Write permission to the Certificate object.
  • 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

{guid}

Specify this parameter as part of the URL. A GUID that uniquely identifies a Certificate object. To get the GUID, call POST Config/DnToGuid or in the Policy tree, use the X509 User Certificate value that appears on the Support Attributes tab. Enclose the GUID in curly braces. For example, {724a3db3-8855-4ea9-986f-519f0c571148}.

Location of a X509 GUID in the UI

AttributeData

Specify this parameter as part of the JSON body. An array of Name and Value config attributes to change for the certificate.

To clear every attribute value, specify null rather than an array of strings. For example: value:null.

  • Name: The Attribute name that appears on the Certificate Support tab. Use the Add button to find attributes that are not currently set. You can try one of these attributes as appropriate: Parent class—X509 Certificate Base.
  • Value: An array of one or more updated values.

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: The Config attribute changed successfully. If the value is now null, the attribute no longer appears on Support tab.

HTTP 400

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

  • Error: Present only if an error occurred during the API call.
  • Success: false: The Config attribute failed to update based on the accompanying Error for the following reasons:
    • Failed to update attributes. [Config error].
    • For attributes [Names] locked policy effective values will be used.

    • For some attributes the policy values are locked. For attributes [Names] the locked policy effective values will be used instead.

    • Invalid certificate GUID. The object with GUID [Guid] does not exist or you do not have permissions to view it.
    • Invalid certificate GUID. The object with GUID [Guid] has class [configObject.TypeName] and it is not a certificate.
    • Invalid certificate GUID. The value [Guid] is null, empty, or in an invalid format.
    • Invalid request data. An attribute name cannot be null, empty, or white space.

    • Invalid request data. The request is null or does not contain attributes to update.
    • Invalid request data. There is a duplicate attribute name [Name].
    • Invalid request data. Value for attribute [Name] cannot be converted to array of strings.
    • Invalid request data. Value for attribute [Name] cannot be converted to array.
    • Locked policy values. The attributes [Names] will use the effective values on the locked policy instead.

Example 1: Change the city and state, clear email address on a certificate

Request for Example 1

PUT https://tpp.venafi.example/vedsdk/Certificates/{724a3db3-8855-4ea9-986f-519f0c571148}
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "AttributeData":[
      {
         "Name":"City",
         "Value":[
            "Seattle"
         ]
      },
      {
         "Name":"State",
         "Value":[
            "WA"
         ]
      },
      {
         "Name":"X509 SubjectAltName RFC822",
         "Value":null
      }
   ]
}

Response Example 1

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

Example 2: Disable or retire a certificate

The following example shows you how to disable or retire a certificate. The certificate status remains disabled until you clear the Processing Disabled checkbox in the UI or all PUT Certificates/{guid} with a Disabled value of 0.

Request for Example 2

PUT https://tpp.venafi.example/vedsdk/Certificates/{724a3db3-8855-4ea9-986f-519f0c571148}
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "AttributeData":[
      {
         "Name":"Description",
         "Value":[
            "This certificate was retired on 2019-Oct-25"
         ]
      },
      {
         "Name":"Disabled",
         "Value":[
            "1"
         ]
      }
   ]
}

Response for Example 2

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