GET Client

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

Pass at least one input parameter as part of the URL.

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

Returns a maximum of 500 search results. Total number of records that match search parameters appears in the X-Record-Count response header. You can use the response header value to determine whether to rerun this API method with additional filtering.

  • 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.
  • FQDN: The FQDN server name where the registered client is installed.
  • OsName: The host operating system where the registered client is installed.
  • Username: The domain or local user name that runs the registered client.

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 1: Find all agent Client IDs for particular host and user name

Request for Example 1

GET https://tpp.venafi.example/vedsdk/Client/?Hostname=testhost&Username=user
Authorization:Bearer 4MyGeneratedBearerTknz==

Response for Example 1

HTTP/1.1 200 OK
X-Record-Count 2
{
   [
      {
         "ClientId":"4451",
         "ClientType":"VenafiAgent",
         "FQDN":"testhost.venafi.com",
         "OsName":"Windows",
         "Username":"root"
      },
      {
         "ClientId":"4452",
         "ClientType":"VenafiAgent",
         "FQDN":"testhost.venafi.com",
         "OsName":"Windows",
         "Username":"root"
      }
   ]
}

Example 2: Find agent Client IDs for geographical region

Request for Example 2

GET https://tpp.venafi.example/vedsdk/Client/?Region=us
Authorization:Bearer 4MyGeneratedBearerTknz==

Response for Example 2

HTTP/1.1 200 OK
{
   [
      {
         "ClientId":"4451",
         "ClientType":"VenafiAgent",
         "FQDN":"testhost.venafi.com",
         "OsName":"Windows",
         "Username":"root"
      },
      {
         "ClientId":"4452",
         "ClientType":"VenafiAgent",
         "FQDN":"testhost.venafi.com",
         "OsName":"Windows",
         "Username":"root"
      }
   ]
}