GET Client/Details

Returns information about registered Server Agent or Agentless clients including the total of both.

Requirements

  • Permissions: The caller must have Read permission to the client entry.
  • Token scope:  Agent

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

When adding query parameters, use the /? syntax. If you are not passing any parameters, make sure the URL ends with a trailing slash. Otherwise, some environments, such as cURL and PowerShell, return a HTTP 307 Temporary Redirect message.

Input parameters

Name

Description

ClientVersion

(Optional) The exact Trust Protection Platform agent version number.

ClientType

(Optional) The exact registered client category. Specify one of the following:

  • VenafiAgent: Return information about server agent clients.
  • AgentJuniorMachine: Return information about Windows user agent clients running as system.
  • AgentJuniorUser: Return information about Windows user agent clients running as user.
  • Portal: Return information about end user portal clients.
  • Agentless: Return information about agentless clients.
  • PreEnrollment: Return information about Pre-enrollment user clients.
  • iOS: Return information about IOS clients.
  • Android: Return information about Android clients.

HostName

(Optional) The exact or partial hostname, Fully Qualified Domain Name (FQDN), or domain name where the registered client is installed.

IPAddress

(Optional) The exact IPv4 or IPV6 address of the system where the registered client is installed.

LastSeenOn

(Optional) The exact date of clients connecting to Trust Protection Platform. For example YYYY-MM-DD.

LastSeenOnGreater

(Optional) Find information about clients connecting to Trust Protection Platformafter this exact UTC time. Use the ISO 8601 format, for example YYYY-MM-DDTHH:MM:SS.mmmmmmmZ.

LastSeenOnLess

(Optional) Find information about all clients connecting to Trust Protection Platformbefore this exact UTC time. For a time range, make sure the LastSeenOnGreater time is older than the LastSeenOnLess time. Use the ISO 8601 format, for example YYYY-MM-DDTHH:MM:SS.mmmmmmmZ.

MACAddress

(Optional) The exact or partial MAC address where the registered client is installed. Set the MAC Address with or without colon or dash separators, for example 00:AA:BB:CC:EE:00, 00-AA-BB-CC-EE-00 , or 00AABBCCEE00.

OSName

(Optional) The exact operating system name of the system where the registered client is installed. Specify one of the following:

  • AIX
  • Android
  • BlackBerry
  • BSD
  • HPux
  • iOS
  • Linux
  • MacOS
  • Other
  • Solaris
  • Unknown
  • Windows
  • zOS

OSVersion

(Optional) The exact operating system version of the system where the registered client is installed.

Region

(Optional) The set of clients for a particular geographic area, such as a state or territory. For example Region=US.

SerialNumber

(Optional) The exact or partial hardware serial number of the system where the registered client is installed.

SID

(Optional) The exact Security Identifier (SID) that corresponds to the UserName that is registered with the client.

UserName

(Optional) The exact or partial domain or local user name that runs the registered client.

VirtualMachineId

(Optional) The virtual machine identifier from the UI. For example, VirtualMachineId=1.

Returns

Response description

Name

Description

HTTP 200

  • CertificateDevice: The Distinguished Name (DN) of the device associated with the registered client that holds certificates.
  • ClientId: The Client ID is assigned to the Agent after registration with the Trust Protection Platform server.
  • ClientType:
    • VenafiAgent: The registered client is a Server Agent client.
    • AgentJuniorMachine: The Windows user agent client runs as system.
    • AgentJuniorUser: The Windows user agent clients runs as user.
    • Portal: The registered client is an end user portal client.
    • Agentless: The registered client is an agentless client.
    • PreEnrollment: The registered client is a Pre-enrollment user client.
    • iOS: The registered client runs on the iOS operating system.
    • Android: The registered client runs on the Android operating system.
  • ClientVersion: The Server Agent version number.

  • CreatedOn: The date and time of Server Agent or agentless client registration.
  • DnsName: The FQDN Domain Name Server where the registered client is installed.
  • EffectiveWork:  An array of work objects that apply to the registered client. Work objects are tasks such as device creation, certificate discovery and provisioning, SSH discovery and provisioning, and SSH log monitoring and upgrading.

    DID YOU KNOW?  Work refers to automated tasks that include configurations and operations. These tasks use SSH connections or Venafi Server Agents that are installed on various systems in your network.

  • FQDN: The FQDN server name where the registered client is installed.
  • Groups: If the registered client is a member of one or more Agent groups, returns an array of Agent group names.
  • HostDomain: The domain name where the registered client is installed.
  • HostName: The hostname, Fully Qualified Domain Name (FQDN) or domain name.
  • LastSeenOn: The last date the registered client connected to Trust Protection Platform. For example, YYYY-MM-DD.
  • Networks: An array that describes each Network Interface Card (NIC) or method of network connectivity where the registered client is installed:
    • IpAddress: The IPv4 or IPv6 address.
    • MacAddress: The MAC address.
  • OsBuild: The host operating system build version where the registered client is installed.
  • OsName: The host operating system where the registered client is installed.
  • OsServicePack: The host operating system service pack version.
  • OsVersion: The host operating system version where the registered client is installed.
  • Region: The location of the data center, for example us-east-1d.
  • SerialNumber: The host serial number where the registered client is installed.
  • SshDevice: The Distinguished Name (DN) of the device associated with registered client that holds SSH keys.
  • SystemArchitecture: The host operating system bit version where the registered client is installed. For example, x32 or x64.
  • SystemChassis: The host model name where the registered client is installed. For example, Dell.
  • SystemManufacturer: The host computer manufacturer name where the registered client is installed.
  • SystemModel: The host model number where the registered client is installed.
  • TrustLevel: A customer-defined value from 0-127 that describes the trust level for a server agent. The default, 0, indicates that the agent is not trusted, a value of 50 can indicate that the registered Server Agent has a valid registration password.
  • UserName: The domain or local user name that runs the registered client.
  • VirtualMachineId: The unique identifier for the virtual machine. For example i-07a6c5394590c4b4c.

HTTP 204

No client data was found. If necessary, adjust your input parameters and retry.

HTTP 307

If the method is missing a slash (/) at the end of the URL or between the query parameters, this message appears: There is no operation listening for [Web SDK method], but there is an operation listening for [Web SDK method/], so you are being redirected there.

Example: Get the virtual machine ID for a host

Request

GET https://tpp.venafi.example/vedsdk/Client/Details?VirtualMachineId=1
Authorization:Bearer 4MyGeneratedBearerTknz==

Response

HTTP/1.1 200 OK
[
   {
      "CertificateDevice":"\\VED\\Policy\\Devices\\i-018d929e5fe3cfbb9",
      "ClientId":"2",
      "ClientType":"VenafiAgent",
      "ClientVersion":"17.1.0.0",
      "CreatedOn":"01/17/2017 21:53:17",
      "DnsName":"i-018d929e5fe3cfbb9",
      "EffectiveWork":[
         "All Server Agents - Device Placement",
         "All Server Agents - Certificate Discovery"
      ],
      "FQDN":"i-018d929e5fe3cfbb9",
      "Groups":[
         "All Server Agents"
      ],
      "HostDomain":"",
      "Hostname":"i-018d929e5fe3cfbb9",
      "LastSeenOn":"02/05/2017 02:39:07",
      "Networks":[
         {
            "IpAddress":"10.0.0.114",
            "MacAddress":"12-98-E4-38-6A-C2"
         }
      ],
      "OsBuild":"7601",
      "OsName":"Windows",
      "OsServicePack":"0",
      "OsVersion":"6.1.7601",
      "Region":"us-east-1d",
      "SerialNumber":"ec2e0fb1-bc52-e302-4f87-1035f757c8af",
      "SshDevice":"\\VED\\Policy\\Devices\\i-018d929e5fe3cfbb9",
      "SystemArchitecture":"x64",
      "SystemChassis":"None",
      "SystemManufacturer":"Amazon Web Services",
      "SystemModel":"HVM domU",
      "TrustLevel":"50",
      "Username":"SYSTEM",
      "VirtualMachineId":"i-018d929e5fe3cfbb9"
   },
   {
      "CertificateDevice":"\\VED\\Policy\\Devices\\ip-172-31-23-142.us-west-2.compute.internal",
      "ClientId":"4",
      "ClientType":"VenafiAgent",
      "ClientVersion":"17.1.0.0",
      "CreatedOn":"01/25/2017 15:10:57",
      "DnsName":"ip-172-31-23-142.us-west-2.compute.internal",
      "EffectiveWork":[
         "All Server Agents - Device Placement",
         "All Server Agents - Certificate Discovery"
      ],
      "FQDN":"ip-172-31-23-142.us-west-2.compute.internal",
      "Groups":[
         "All Server Agents"
      ],
      "HostDomain":"us-west-2.compute.internal",
      "Hostname":"ip-172-31-23-142",
      "LastSeenOn":"01/25/2017 15:10:58",
      "Networks":[
         {
            "IpAddress":"172.31.23.142",
            "MacAddress":"02-12-09-46-D5-55"
         },
         {
            "IpAddress":"fe80::12:9ff:fe46:d555",
            "MacAddress":"02-12-09-46-D5-55"
         }
      ],
      "OsBuild":"Unknown",
      "OsName":"Linux",
      "OsServicePack":"0",
      "OsVersion":"3.10.0.514",
      "Region":"",
      "SerialNumber":"ec2ac14c-b07c-ec83-f792-8d75485dd1e2",
      "SshDevice":"\\VED\\Policy\\Devices\\ip-172-31-23-142.us-west-2.compute.internal",
      "SystemArchitecture":"x64",
      "SystemChassis":"None",
      "SystemManufacturer":"Amazon Web Services",
      "SystemModel":"HVM domU",
      "TrustLevel":"50",
      "Username":"root",
      "VirtualMachineId":"i-07a6c5394590c4b4c"
   }
]