Update API docs: add get host by device token (#13761)
- Add get host by device token - Remove this API route from the contributor docs
This commit is contained in:
Noah Talerman
@@ -2216,7 +2216,6 @@ currently pending.
|
||||
|
||||
Device-authenticated routes are routes used by the Fleet Desktop application. Unlike most other routes, Fleet user's API token does not authenticate them. They use a device-specific token.
|
||||
|
||||
- [Get device's host](#get-devices-host)
|
||||
- [Refetch device's host](#refetch-devices-host)
|
||||
- [Get device's Google Chrome profiles](#get-devices-google-chrome-profiles)
|
||||
- [Get device's mobile device management (MDM) and Munki information](#get-devices-mobile-device-management-mdm-and-munki-information)
|
||||
@@ -2228,198 +2227,6 @@ Device-authenticated routes are routes used by the Fleet Desktop application. Un
|
||||
- [Trigger FileVault key escrow](#trigger-filevault-key-escrow)
|
||||
- [Report an agent error](#report-an-agent-error)
|
||||
|
||||
#### Get device's host
|
||||
|
||||
Returns the host information about the device that makes the request.
|
||||
|
||||
`GET /api/v1/fleet/device/{token}`
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Name | Type | In | Description |
|
||||
| ----- | ------ | ---- | ---------------------------------- |
|
||||
| token | string | path | The device's authentication token. |
|
||||
|
||||
##### Example
|
||||
|
||||
`GET /api/v1/fleet/device/abcdef012456789`
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
```json
|
||||
{
|
||||
"host": {
|
||||
"created_at": "2021-08-19T02:02:22Z",
|
||||
"updated_at": "2021-08-19T21:14:58Z",
|
||||
"software": [
|
||||
{
|
||||
"id": 408,
|
||||
"name": "osquery",
|
||||
"version": "4.5.1",
|
||||
"source": "rpm_packages",
|
||||
"generated_cpe": "",
|
||||
"vulnerabilities": null
|
||||
},
|
||||
{
|
||||
"id": 1146,
|
||||
"name": "tar",
|
||||
"version": "1.30",
|
||||
"source": "rpm_packages",
|
||||
"generated_cpe": "",
|
||||
"vulnerabilities": null
|
||||
},
|
||||
{
|
||||
"id": 321,
|
||||
"name": "SomeApp.app",
|
||||
"version": "1.0",
|
||||
"source": "apps",
|
||||
"bundle_identifier": "com.some.app",
|
||||
"last_opened_at": "2021-08-18T21:14:00Z",
|
||||
"generated_cpe": "",
|
||||
"vulnerabilities": null
|
||||
}
|
||||
],
|
||||
"id": 1,
|
||||
"detail_updated_at": "2021-08-19T21:07:53Z",
|
||||
"label_updated_at": "2021-08-19T21:07:53Z",
|
||||
"last_enrolled_at": "2021-08-19T02:02:22Z",
|
||||
"seen_time": "2021-08-19T21:14:58Z",
|
||||
"refetch_requested": false,
|
||||
"hostname": "23cfc9caacf0",
|
||||
"uuid": "309a4b7d-0000-0000-8e7f-26ae0815ede8",
|
||||
"platform": "rhel",
|
||||
"osquery_version": "4.5.1",
|
||||
"os_version": "CentOS Linux 8.3.2011",
|
||||
"build": "",
|
||||
"platform_like": "rhel",
|
||||
"code_name": "",
|
||||
"uptime": 210671000000000,
|
||||
"memory": 16788398080,
|
||||
"cpu_type": "x86_64",
|
||||
"cpu_subtype": "158",
|
||||
"cpu_brand": "Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz",
|
||||
"cpu_physical_cores": 12,
|
||||
"cpu_logical_cores": 12,
|
||||
"hardware_vendor": "",
|
||||
"hardware_model": "",
|
||||
"hardware_version": "",
|
||||
"hardware_serial": "",
|
||||
"computer_name": "23cfc9caacf0",
|
||||
"display_name": "23cfc9caacf0",
|
||||
"public_ip": "",
|
||||
"primary_ip": "172.27.0.6",
|
||||
"primary_mac": "02:42:ac:1b:00:06",
|
||||
"distributed_interval": 10,
|
||||
"config_tls_refresh": 10,
|
||||
"logger_tls_period": 10,
|
||||
"team_id": null,
|
||||
"pack_stats": null,
|
||||
"team_name": null,
|
||||
"additional": {},
|
||||
"gigs_disk_space_available": 46.1,
|
||||
"percent_disk_space_available": 73,
|
||||
"disk_encryption_enabled": true,
|
||||
"dep_assigned_to_fleet": false,
|
||||
"users": [
|
||||
{
|
||||
"uid": 0,
|
||||
"username": "root",
|
||||
"type": "",
|
||||
"groupname": "root",
|
||||
"shell": "/bin/bash"
|
||||
},
|
||||
{
|
||||
"uid": 1,
|
||||
"username": "bin",
|
||||
"type": "",
|
||||
"groupname": "bin",
|
||||
"shell": "/sbin/nologin"
|
||||
}
|
||||
],
|
||||
"labels": [
|
||||
{
|
||||
"created_at": "2021-08-19T02:02:17Z",
|
||||
"updated_at": "2021-08-19T02:02:17Z",
|
||||
"id": 6,
|
||||
"name": "All Hosts",
|
||||
"description": "All hosts which have enrolled in Fleet",
|
||||
"query": "SELECT 1;",
|
||||
"platform": "",
|
||||
"label_type": "builtin",
|
||||
"label_membership_type": "dynamic"
|
||||
},
|
||||
{
|
||||
"created_at": "2021-08-19T02:02:17Z",
|
||||
"updated_at": "2021-08-19T02:02:17Z",
|
||||
"id": 9,
|
||||
"name": "CentOS Linux",
|
||||
"description": "All CentOS hosts",
|
||||
"query": "SELECT 1 FROM os_version WHERE platform = 'centos' OR name LIKE '%centos%'",
|
||||
"platform": "",
|
||||
"label_type": "builtin",
|
||||
"label_membership_type": "dynamic"
|
||||
},
|
||||
{
|
||||
"created_at": "2021-08-19T02:02:17Z",
|
||||
"updated_at": "2021-08-19T02:02:17Z",
|
||||
"id": 12,
|
||||
"name": "All Linux",
|
||||
"description": "All Linux distributions",
|
||||
"query": "SELECT 1 FROM osquery_info WHERE build_platform LIKE '%ubuntu%' OR build_distro LIKE '%centos%';",
|
||||
"platform": "",
|
||||
"label_type": "builtin",
|
||||
"label_membership_type": "dynamic"
|
||||
}
|
||||
],
|
||||
"packs": [],
|
||||
"status": "online",
|
||||
"display_text": "23cfc9caacf0",
|
||||
"batteries": [
|
||||
{
|
||||
"cycle_count": 999,
|
||||
"health": "Good"
|
||||
}
|
||||
],
|
||||
"mdm": {
|
||||
"encryption_key_available": false,
|
||||
"enrollment_status": null,
|
||||
"name": "",
|
||||
"server_url": null,
|
||||
"macos_settings": {
|
||||
"disk_encryption": null,
|
||||
"action_required": null
|
||||
},
|
||||
"macos_setup": {
|
||||
"bootstrap_package_status": "installed",
|
||||
"detail": "",
|
||||
"bootstrap_package_name": "test.pkg"
|
||||
},
|
||||
"profiles": [
|
||||
{
|
||||
"profile_id": 999,
|
||||
"name": "profile1",
|
||||
"status": "verifying",
|
||||
"operation_type": "install",
|
||||
"detail": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"org_logo_url": "https://example.com/logo.jpg",
|
||||
"license": {
|
||||
"tier": "free",
|
||||
"expiration": "2031-01-01T00:00:00Z"
|
||||
},
|
||||
"global_config": {
|
||||
"mdm": {
|
||||
"enabled_and_configured": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Refetch device's host
|
||||
|
||||
Same as [Refetch host route](https://fleetdm.com/docs/using-fleet/rest-api#refetch-host) for the current device.
|
||||
|
||||
@@ -1741,6 +1741,7 @@ None.
|
||||
- [Get hosts summary](#get-hosts-summary)
|
||||
- [Get host](#get-host)
|
||||
- [Get host by identifier](#get-host-by-identifier)
|
||||
- [Get host by device token](#get-host-by-device-token)
|
||||
- [Delete host](#delete-host)
|
||||
- [Refetch host](#refetch-host)
|
||||
- [Transfer hosts to a team](#transfer-hosts-to-a-team)
|
||||
@@ -2533,6 +2534,200 @@ Returns the information of the host specified using the `uuid`, `osquery_host_id
|
||||
|
||||
> Note: `installed_paths` may be blank depending on installer package. For example, on Linux, RPM-installed packages do not provide installed path information.
|
||||
|
||||
#### Get host by device token
|
||||
|
||||
Returns a subset of information about the host specified by `token`. To get all information about a host, use the "Get host" endpoint [here](#get-host).
|
||||
|
||||
This is the API route used by the **My device** page in Fleet desktop to display information about the host to the end user.
|
||||
|
||||
`GET /api/v1/fleet/device/{token}`
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Name | Type | In | Description |
|
||||
| ----- | ------ | ---- | ---------------------------------- |
|
||||
| token | string | path | The device's authentication token. |
|
||||
|
||||
##### Example
|
||||
|
||||
`GET /api/v1/fleet/device/abcdef012456789`
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
```json
|
||||
{
|
||||
"host": {
|
||||
"created_at": "2021-08-19T02:02:22Z",
|
||||
"updated_at": "2021-08-19T21:14:58Z",
|
||||
"software": [
|
||||
{
|
||||
"id": 408,
|
||||
"name": "osquery",
|
||||
"version": "4.5.1",
|
||||
"source": "rpm_packages",
|
||||
"generated_cpe": "",
|
||||
"vulnerabilities": null
|
||||
},
|
||||
{
|
||||
"id": 1146,
|
||||
"name": "tar",
|
||||
"version": "1.30",
|
||||
"source": "rpm_packages",
|
||||
"generated_cpe": "",
|
||||
"vulnerabilities": null
|
||||
},
|
||||
{
|
||||
"id": 321,
|
||||
"name": "SomeApp.app",
|
||||
"version": "1.0",
|
||||
"source": "apps",
|
||||
"bundle_identifier": "com.some.app",
|
||||
"last_opened_at": "2021-08-18T21:14:00Z",
|
||||
"generated_cpe": "",
|
||||
"vulnerabilities": null
|
||||
}
|
||||
],
|
||||
"id": 1,
|
||||
"detail_updated_at": "2021-08-19T21:07:53Z",
|
||||
"label_updated_at": "2021-08-19T21:07:53Z",
|
||||
"last_enrolled_at": "2021-08-19T02:02:22Z",
|
||||
"seen_time": "2021-08-19T21:14:58Z",
|
||||
"refetch_requested": false,
|
||||
"hostname": "23cfc9caacf0",
|
||||
"uuid": "309a4b7d-0000-0000-8e7f-26ae0815ede8",
|
||||
"platform": "rhel",
|
||||
"osquery_version": "4.5.1",
|
||||
"os_version": "CentOS Linux 8.3.2011",
|
||||
"build": "",
|
||||
"platform_like": "rhel",
|
||||
"code_name": "",
|
||||
"uptime": 210671000000000,
|
||||
"memory": 16788398080,
|
||||
"cpu_type": "x86_64",
|
||||
"cpu_subtype": "158",
|
||||
"cpu_brand": "Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz",
|
||||
"cpu_physical_cores": 12,
|
||||
"cpu_logical_cores": 12,
|
||||
"hardware_vendor": "",
|
||||
"hardware_model": "",
|
||||
"hardware_version": "",
|
||||
"hardware_serial": "",
|
||||
"computer_name": "23cfc9caacf0",
|
||||
"display_name": "23cfc9caacf0",
|
||||
"public_ip": "",
|
||||
"primary_ip": "172.27.0.6",
|
||||
"primary_mac": "02:42:ac:1b:00:06",
|
||||
"distributed_interval": 10,
|
||||
"config_tls_refresh": 10,
|
||||
"logger_tls_period": 10,
|
||||
"team_id": null,
|
||||
"pack_stats": null,
|
||||
"team_name": null,
|
||||
"additional": {},
|
||||
"gigs_disk_space_available": 46.1,
|
||||
"percent_disk_space_available": 73,
|
||||
"disk_encryption_enabled": true,
|
||||
"dep_assigned_to_fleet": false,
|
||||
"users": [
|
||||
{
|
||||
"uid": 0,
|
||||
"username": "root",
|
||||
"type": "",
|
||||
"groupname": "root",
|
||||
"shell": "/bin/bash"
|
||||
},
|
||||
{
|
||||
"uid": 1,
|
||||
"username": "bin",
|
||||
"type": "",
|
||||
"groupname": "bin",
|
||||
"shell": "/sbin/nologin"
|
||||
}
|
||||
],
|
||||
"labels": [
|
||||
{
|
||||
"created_at": "2021-08-19T02:02:17Z",
|
||||
"updated_at": "2021-08-19T02:02:17Z",
|
||||
"id": 6,
|
||||
"name": "All Hosts",
|
||||
"description": "All hosts which have enrolled in Fleet",
|
||||
"query": "SELECT 1;",
|
||||
"platform": "",
|
||||
"label_type": "builtin",
|
||||
"label_membership_type": "dynamic"
|
||||
},
|
||||
{
|
||||
"created_at": "2021-08-19T02:02:17Z",
|
||||
"updated_at": "2021-08-19T02:02:17Z",
|
||||
"id": 9,
|
||||
"name": "CentOS Linux",
|
||||
"description": "All CentOS hosts",
|
||||
"query": "SELECT 1 FROM os_version WHERE platform = 'centos' OR name LIKE '%centos%'",
|
||||
"platform": "",
|
||||
"label_type": "builtin",
|
||||
"label_membership_type": "dynamic"
|
||||
},
|
||||
{
|
||||
"created_at": "2021-08-19T02:02:17Z",
|
||||
"updated_at": "2021-08-19T02:02:17Z",
|
||||
"id": 12,
|
||||
"name": "All Linux",
|
||||
"description": "All Linux distributions",
|
||||
"query": "SELECT 1 FROM osquery_info WHERE build_platform LIKE '%ubuntu%' OR build_distro LIKE '%centos%';",
|
||||
"platform": "",
|
||||
"label_type": "builtin",
|
||||
"label_membership_type": "dynamic"
|
||||
}
|
||||
],
|
||||
"packs": [],
|
||||
"status": "online",
|
||||
"display_text": "23cfc9caacf0",
|
||||
"batteries": [
|
||||
{
|
||||
"cycle_count": 999,
|
||||
"health": "Good"
|
||||
}
|
||||
],
|
||||
"mdm": {
|
||||
"encryption_key_available": false,
|
||||
"enrollment_status": null,
|
||||
"name": "",
|
||||
"server_url": null,
|
||||
"macos_settings": {
|
||||
"disk_encryption": null,
|
||||
"action_required": null
|
||||
},
|
||||
"macos_setup": {
|
||||
"bootstrap_package_status": "installed",
|
||||
"detail": "",
|
||||
"bootstrap_package_name": "test.pkg"
|
||||
},
|
||||
"profiles": [
|
||||
{
|
||||
"profile_id": 999,
|
||||
"name": "profile1",
|
||||
"status": "verifying",
|
||||
"operation_type": "install",
|
||||
"detail": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"org_logo_url": "https://example.com/logo.jpg",
|
||||
"license": {
|
||||
"tier": "free",
|
||||
"expiration": "2031-01-01T00:00:00Z"
|
||||
},
|
||||
"global_config": {
|
||||
"mdm": {
|
||||
"enabled_and_configured": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Delete host
|
||||
|
||||
Deletes the specified host from Fleet. Note that a deleted host will fail authentication with the previous node key, and in most osquery configurations will attempt to re-enroll automatically. If the host still has a valid enroll secret, it will re-enroll successfully.
|
||||
|
||||
Reference in New Issue
Block a user