POST Client/Delete

Deletes registered client agents and returns status information about the deletion. The Client/Delete method:

  • Removes only registered agent information for the specified Client Id. Permanently deletes a maximum of 5,000 Client records and lists any ClientIds that could not be deleted in the Errors response.

  • Removes or preserves corresponding Device objects, certificates, or discovery information in the Trust Protection Platform.

  • Ignores additional parameters, such as Fully Qualified Domain Name (FQDN).

  • Logs information, such as the deleted Client IDs, the FQDN and the Web SDK user who performed the deletion.

Requirements

  • Permissions:  The caller must have either a Master Admin or View permission. The caller also needs Read permission and Delete permission on a group in which the Client is a member.
  • Token scope:  Agent:Delete

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

Clients

Delete an array of one or more Client Ids that are assigned to registered Agents. The maximum number of ClientIDs is 5,000.

DeleteAssociatedDevices

(Optional) Manage corresponding device, certificate, and discovery information in the Policy tree and Secret Store:

  • true: For a registered Agent, delete the associated Device objects, and only certificates that belong to the associated device. Delete any related Discovery information. Preserve unrelated device, certificate, and Discovery information in other locations of the Policy tree and Secret Store.

  • false: Default. Remove only the registered Agent. If the registered Agent has corresponding Device objects, certificates, or discovery information, preserve the information in the Trust Protection Platform.

TIP   Specify true, when the Agent is no longer physically deployed and you want to clean up the device inventory and discovery artifacts in Trust Protection Platform.

Returns

Response description

Name

Description

HTTP 200

The following data in the message body:

  • DeletedCount: The number of deleted Client records.
  • Errors: The reason why the Client/Delete could not remove the registered agent. Reasons include invalid permissions for a particular ClientId, or the ClientId is missing, invalid, or already deleted. For example, if the ClientId was already deleted, the value is EntryDoesNotExist.

HTTP 400

Returns Bad Request when the request has more than 5,000 ClientIds.

Example: Delete a set of Client IDs

Request

POST https://tpp.venafi.example/vedsdk/Client/Delete
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "Clients":[
      {
         "ClientId":"10123"
      },
      {
         "ClientId":"9178"
      }
   ]
}

Response

HTTP/1.1 200 OK
{
   "Errors":[],
   "DeletedCount":2
}