Manage devices

You can use the APIv2 to fully manage a device. Below are some examples of actions that can be taken.

Activating a device

When a device is activated in Fleet Manager, the import of the configuration is executed as an additional step.
So, after activating a device with APIv2, this step needs to be taken too.

First, activate the device (endpoint):

curl --request POST \
     --url "<<url>>:443/api/agents/activate" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'content-type: application/json' \
     --header "Authorization: Bearer $bearer_token"
     --data '
     [
          {
               "publicId": "$agent_id",
               "name": "$name_of_agent"
          }
     ]'

Second, import the configuration (endpoint):

curl --request PUT \
     --url "<<url>>:443/api/agents/configuration/import" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'content-type: application/json' \
     --header 'Api-Branding: <<apiBranding>>' \
     --header "Authorization: Bearer $bearer_token"
     --data '
     [
          {
               "publicId": "$agent_id"
          }
     ]'

Get the IP address and port of the HTTP Server

To get the IP address and the port of a service you need to request several specific fields from the Agent endpoint. The fields you have to request are:

- devices.publicId
- devices.ipAddress
- servers.publicId
- servers.name
- servers.port
- servers.device

curl --request GET \
     --url "<<url>>:443/api/agents/$agent_id?fields=devices.publicid,devices.ipAddress,servers.publicId,servers.name,servers.port,servers.device" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'content-type: application/json' \
     --header "Authorization: Bearer $bearer_token"

Instead of using the full name and comma-separated fields, you can also group fields by using parentheses as in the example below.

curl --request GET \
     --url "<<url>>:443/api/agents/$agent_id?fields=devices(publicId,ipAddress),servers(publicId,name,port,device)" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'content-type: application/json' \
     --header "Authorization: Bearer $bearer_token"

Regardless of the syntax of the query, the output will be identical.

{
	"status": "success",
	"type": "Agent",
	"data": {
		"publicId": "Ss80MfTQt1p7",              <-- AgentId
		"devices": [
			{
				"publicId": "96v1aCZnHXC5",      <-- The device the service is running on
				"ipAddress": "192.168.140.245"   <-- IP address
			}
		],
		"servers": [
			{
				"publicId": "7J78tFCWUAtb",      <-- The service
				"name": "Local web interface",
				"port": 80,                      <-- Port number
				"device": {
					"publicId": "96v1aCZnHXC5",  <-- The device the service is running on
					"reference": {
						"name": "AgentDevice"
					}
				}
			}
		]
	}
}

Get the WAN IP address

To get the WAN IP address you need to request networkValues.value and networkValues.name from the Agent endpoint.

curl --request GET \
     --url "<<url>>:443/api/agents/$agent_id?fields=networkValues.value,networkValues.name" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'content-type: application/json' \
     --header "Authorization: Bearer $bearer_token"

The output.

{
	"status": "success",
	"type": "Agent",
	"data": {
		"publicId": "Ss80MfTQt1p7",
		"networkValues": [
			{
				"name": "addresses",
				"value": [
					"192.168.146.6"       <-- WAN IP address
				]
			},
			{
				"name": "dnsServers",
				"value": [
					"1.1.1.1",
					"9.9.9.9"
				]
			},
			{
				"name": "gateways",
				"value": [
					"192.168.146.1"
				]
			}
		]
	}
}

Get the list of connected users

To get the list of connected users you need to request connectedUsers from the Agent endpoint.

curl --request GET \
     --url "<<url>>:443/api/agents/$agent_id?fields=connectedUsers" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'content-type: application/json' \
     --header "Authorization: Bearer $bearer_token"

The output.

{
	"status": "success",
	"type": "Agent",
	"data": {
		"publicId": "Ss80MfTQt1p7",
		"connectedUsers": [
			{
				"publicId": "Cc20JEniwdX2",
				"name": "Demo user"       <-- Connected user
			}
		]
	}
}

Enable Stealth Mode on a device

To enable Stealth Mode on a device you need to use {"useStunnel":true} in the body (payload).

curl --request PATCH \
     --url "<<url>>:443/api/agents/$agent_id" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'content-type: application/json' \
     --header "Authorization: Bearer $bearer_token"\
     --data '
     [
          {
               "useStunnel":true
          }
     ]'

See if there is a configuration difference

There are two ways a configuration difference arises:

After making a change in the platform. To resolve this, the configuration needs to be pushed to a device.
After changing on the local device, by using the local web interface or a USB stick. To resolve this, the configuration needs to be imported from the device.

The field config.differentConfigs on an agent can be used to get the configuration status (in sync or not in sync) of a device.

curl --request GET \
     --url "<<url>>:443/api/agents/$agent_id?fields=config.differentConfigs" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'content-type: application/json' \
     --header "Authorization: Bearer $bearer_token"

The output:

false: in sync
true: not in sync

{
  "status": "success",
  "type": "Agent",
  "data": {
    "publicId": "Ss80MfTQt1p7",
    "config": {
      "publicId": "Ss80MfTQt1p7",
      "differentConfigs": false
    }
  }
}

Get the configuration status for all agents at once.

curl --request GET \
     --url "<<url>>:443/api/agents?fields=config.differentConfigs" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'content-type: application/json' \
     --header "Authorization: Bearer $bearer_token"

See if a device is online

The online status of a device can be retrieved by requesting activeVpnSession from the Agent endpoint. This is the VPN connection from the device to the platform.

curl --request GET \
     --url "<<url>>:443/api/agents?fields=publicId%2Cname%2CactiveVpnSession" \
     --header 'Api-Version: 2' \
     --header "Api-Application: $application_id" \
     --header "Api-Company: $company_id" \
     --header 'content-type: application/json' \
     --header "Authorization: Bearer $bearer_token"

The output can be either:

{}: device is online
null: device is offline

{
    "type": "Agent",
    "data": [
        {
            "publicId": "0aED0Zjnzeli",
            "name": "Demo device 1",
            "activeVpnSession": {}         <-- online
        },
        {
            "publicId": "0eF1cpO1XFEl",
            "name": "Demo device 2",
            "activeVpnSession": null       <-- offline
        }
    ],
    "moreAfter": null,
    "status": "success"
}