From 705373135497207469e39ca3934f97f2fb175a70 Mon Sep 17 00:00:00 2001 From: Ian Littman Date: Tue, 24 Dec 2024 11:49:43 -0700 Subject: [PATCH] Move invite API endpoint docs from Fleet configuration heading to user heading, add missing mfa_enabled fields on invite endpoints (#24986) For #24985. Also rewords rather verbose "these are authenticated endpoints" descriptions for both subheadings. --- docs/REST API/rest-api.md | 991 +++++++++++++++++++------------------- 1 file changed, 500 insertions(+), 491 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index c0cf0ac76fbf..fec0670a4af8 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -736,14 +736,9 @@ Retrieves the specified carve block. This endpoint retrieves the data that was c - [Modify global enroll secrets](#modify-global-enroll-secrets) - [Get team enroll secrets](#get-team-enroll-secrets) - [Modify team enroll secrets](#modify-team-enroll-secrets) -- [Create invite](#create-invite) -- [List invites](#list-invites) -- [Delete invite](#delete-invite) -- [Verify invite](#verify-invite) -- [Update invite](#update-invite) - [Version](#version) -The Fleet server exposes a handful of API endpoints that handle the configuration of Fleet as well as endpoints that manage invitation and enroll secret operations. All the following endpoints require prior authentication meaning you must first log in successfully before calling any of the endpoints documented below. +The Fleet server exposes API endpoints that handle the configuration of Fleet as well as endpoints that manage enroll secret operations. These endpoints require prior authentication, you so you'll need to log in before calling any of the endpoints documented below. ### Get certificate @@ -2089,44 +2084,19 @@ Delete all of a team's existing enroll secrets } ``` -### Create invite +### Version -`POST /api/v1/fleet/invites` +Get version and build information from the Fleet server. + +`GET /api/v1/fleet/version` #### Parameters -| Name | Type | In | Description | -| ----------- | ------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| global_role | string | body | Role the user will be granted. Either a global role is needed, or a team role. | -| email | string | body | **Required.** The email of the invited user. This email will receive the invitation link. | -| name | string | body | **Required.** The name of the invited user. | -| sso_enabled | boolean | body | **Required.** Whether or not SSO will be enabled for the invited user. | -| teams | array | body | _Available in Fleet Premium_. A list of the teams the user is a member of. Each item includes the team's ID and the user's role in the specified team. | +None. #### Example -##### Request body - -```json -{ - "email": "john_appleseed@example.com", - "name": "John", - "sso_enabled": false, - "global_role": null, - "teams": [ - { - "id": 2, - "role": "observer" - }, - { - "id": 3, - "role": "maintainer" - } - ] -} -``` - -`POST /api/v1/fleet/invites` +`GET /api/v1/fleet/version` ##### Default response @@ -2134,404 +2104,150 @@ Delete all of a team's existing enroll secrets ```json { - "invite": { - "created_at": "0001-01-01T00:00:00Z", - "updated_at": "0001-01-01T00:00:00Z", - "id": 3, - "invited_by": 1, - "email": "john_appleseed@example.com", - "name": "John", - "sso_enabled": false, - "teams": [ - { - "id": 10, - "created_at": "0001-01-01T00:00:00Z", - "name": "Apples", - "description": "", - "agent_options": null, - "user_count": 0, - "host_count": 0, - "role": "observer" - }, - { - "id": 14, - "created_at": "0001-01-01T00:00:00Z", - "name": "Best of the Best Engineering", - "description": "", - "agent_options": null, - "user_count": 0, - "host_count": 0, - "role": "maintainer" - } - ] - } + "version": "3.9.0-93-g1b67826f-dirty", + "branch": "version", + "revision": "1b67826fe4bf40b2f45ec53e01db9bf467752e74", + "go_version": "go1.15.7", + "build_date": "2021-03-27", + "build_user": "zwass" } ``` -### List invites - -Returns a list of the active invitations in Fleet. - -`GET /api/v1/fleet/invites` - -#### Parameters +--- -| Name | Type | In | Description | -| --------------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------- | -| order_key | string | query | What to order results by. Can be any column in the invites table. | -| order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `asc` and `desc`. Default is `asc`. | -| query | string | query | Search query keywords. Searchable fields include `name` and `email`. | +## Hosts -#### Example +- [On the different timestamps in the host data structure](#on-the-different-timestamps-in-the-host-data-structure) +- [List hosts](#list-hosts) +- [Count hosts](#count-hosts) +- [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) +- [Transfer hosts to a team by filter](#transfer-hosts-to-a-team-by-filter) +- [Turn off MDM for a host](#turn-off-mdm-for-a-host) +- [Bulk delete hosts by filter or ids](#bulk-delete-hosts-by-filter-or-ids) +- [Get human-device mapping](#get-human-device-mapping) +- [Update custom human-device mapping](#update-custom-human-device-mapping) +- [Get host's device health report](#get-hosts-device-health-report) +- [Get host's mobile device management (MDM) information](#get-hosts-mobile-device-management-mdm-information) +- [Get mobile device management (MDM) summary](#get-mobile-device-management-mdm-summary) +- [Get host's mobile device management (MDM) and Munki information](#get-hosts-mobile-device-management-mdm-and-munki-information) +- [Get aggregated host's mobile device management (MDM) and Munki information](#get-aggregated-hosts-macadmin-mobile-device-management-mdm-and-munki-information) +- [Get host's scripts](#get-hosts-scripts) +- [Get host's software](#get-hosts-software) +- [Get hosts report in CSV](#get-hosts-report-in-csv) +- [Get host's disk encryption key](#get-hosts-disk-encryption-key) +- [Lock host](#lock-host) +- [Unlock host](#unlock-host) +- [Wipe host](#wipe-host) +- [Get host's past activity](#get-hosts-past-activity) +- [Get host's upcoming activity](#get-hosts-upcoming-activity) +- [Add labels to host](#add-labels-to-host) +- [Remove labels from host](#remove-labels-from-host) +- [Live query one host (ad-hoc)](#live-query-one-host-ad-hoc) +- [Live query host by identifier (ad-hoc)](#live-query-host-by-identifier-ad-hoc) -`GET /api/v1/fleet/invites` +### On the different timestamps in the host data structure -##### Default response +Hosts have a set of timestamps usually named with an "_at" suffix, such as created_at, enrolled_at, etc. Before we go +through each of them and what they mean, we need to understand a bit more about how the host data structure is +represented in the database. -`Status: 200` +The table `hosts` is the main one. It holds the core data for a host. A host doesn't exist if there is no row for it in +this table. This table also holds most of the timestamps, but it doesn't hold all of the host data. This is an important +detail as we'll see below. -```json -{ - "invites": [ - { - "created_at": "0001-01-01T00:00:00Z", - "updated_at": "0001-01-01T00:00:00Z", - "id": 3, - "email": "john_appleseed@example.com", - "name": "John", - "sso_enabled": false, - "global_role": "admin", - "teams": [] - }, - { - "created_at": "0001-01-01T00:00:00Z", - "updated_at": "0001-01-01T00:00:00Z", - "id": 4, - "email": "bob_marks@example.com", - "name": "Bob", - "sso_enabled": false, - "global_role": "admin", - "teams": [] - } - ] -} -``` +There's adjacent tables to this one that usually follow the name convention `host_`. Examples of +this are: `host_additional` that holds additional query results, `host_software` that links a host with many rows from +the `software` table. -### Delete invite +- `created_at`: the time the row in the database was created, which usually corresponds to the first enrollment of the host. +- `updated_at`: the last time the row in the database for the `hosts` table was updated. +- `detail_updated_at`: the last time Fleet updated host data, based on the results from the detail queries (this includes updates to host associated tables, e.g. `host_users`). +- `label_updated_at`: the last time Fleet updated the label membership for the host based on the results from the queries ran. +- `last_enrolled_at`: the last time the host enrolled to Fleet. +- `policy_updated_at`: the last time we updated the policy results for the host based on the queries ran. +- `seen_time`: the last time the host contacted the fleet server, regardless of what operation it was for. +- `software_updated_at`: the last time software changed for the host in any way. +- `last_restarted_at`: the last time that the host was restarted. -Delete the specified invite from Fleet. +### List hosts -`DELETE /api/v1/fleet/invites/:id` +`GET /api/v1/fleet/hosts` #### Parameters -| Name | Type | In | Description | -| ---- | ------- | ---- | ---------------------------- | -| id | integer | path | **Required.** The user's id. | - -#### Example +| Name | Type | In | Description | +| ----------------------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| page | integer | query | Page number of the results to fetch. | +| per_page | integer | query | Results per page. | +| order_key | string | query | What to order results by. Can be any column in the hosts table. | +| after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. **Note:** Use `page` instead of `after` | +| order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include 'asc' and 'desc'. Default is 'asc'. | +| status | string | query | Indicates the status of the hosts to return. Can either be 'new', 'online', 'offline', 'mia' or 'missing'. | +| query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4` and the hosts' email addresses (only searched if the query looks like an email address, i.e. contains an '@', no space, etc.). | +| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's `additional` object. | +| team_id | integer | query | _Available in Fleet Premium_. Filters to only include hosts in the specified team. Use `0` to filter by hosts assigned to "No team". | +| policy_id | integer | query | The ID of the policy to filter hosts by. | +| policy_response | string | query | **Requires `policy_id`**. Valid options are 'passing' or 'failing'. | +| software_version_id | integer | query | The ID of the software version to filter hosts by. | +| software_title_id | integer | query | The ID of the software title to filter hosts by. | +| software_status | string | query | The status of the software install to filter hosts by. | +| os_version_id | integer | query | The ID of the operating system version to filter hosts by. | +| os_name | string | query | The name of the operating system to filter hosts by. `os_version` must also be specified with `os_name` | +| os_version | string | query | The version of the operating system to filter hosts by. `os_name` must also be specified with `os_version` | +| vulnerability | string | query | The cve to filter hosts by (including "cve-" prefix, case-insensitive). | +| device_mapping | boolean | query | Indicates whether `device_mapping` should be included for each host. See ["Get host's Google Chrome profiles](#get-hosts-google-chrome-profiles) for more information about this feature. | +| mdm_id | integer | query | The ID of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider and URL). | +| mdm_name | string | query | The name of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider). | +| mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'automatic', 'enrolled', 'pending', or 'unenrolled'. | +| connected_to_fleet | boolean | query | Filter hosts that are talking to this Fleet server for MDM features. In rare cases, hosts can be enrolled to one Fleet server but talk to a different Fleet server for MDM features. In this case, the value would be `false`. Always `false` for Linux hosts. | +| macos_settings | string | query | Filters the hosts by the status of the _mobile device management_ (MDM) profiles applied to hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** | +| munki_issue_id | integer | query | The ID of the _munki issue_ (a Munki-reported error or warning message) to filter hosts by (that is, filter hosts that are affected by that corresponding error or warning message). | +| low_disk_space | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts with less GB of disk space available than this value. Must be a number between 1-100. | +| disable_failing_policies| boolean | query | If `true`, hosts will return failing policies as 0 regardless of whether there are any that failed for the host. This is meant to be used when increased performance is needed in exchange for the extra information. | +| macos_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. | +| bootstrap_package | string | query | _Available in Fleet Premium_. Filters the hosts by the status of the MDM bootstrap package on the host. Valid options are 'installed', 'pending', or 'failed'. | +| os_settings | string | query | Filters the hosts by the status of the operating system settings applied to the hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** | +| os_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** | +| populate_software | string | query | If `false` (or omitted), omits installed software details for each host. If `"without_vulnerability_details"`, include a list of installed software for each host, including which CVEs apply to the installed software versions. `true` adds vulnerability description, CVSS score, and other details when using Fleet Premium. See notes below on performance. | +| populate_policies | boolean | query | If `true`, the response will include policy data for each host. | -`DELETE /api/v1/fleet/invites/123` +> `software_id` is deprecated as of Fleet 4.42. It is maintained for backwards compatibility. Please use the `software_version_id` instead. -##### Default response +> `populate_software` returns a lot of data per host when set, and drastically more data when set to `true` on Fleet Premium. If you need vulnerability details for a large number of hosts, consider setting `populate_software` to `without_vulnerability_details` and pulling vulnerability details from the [Get vulnerability](#get-vulnerability) endpoint, as this returns details once per vulnerability rather than once per vulnerability per host. -`Status: 200` +If `software_title_id` is specified, an additional top-level key `"software_title"` is returned with the software title object corresponding to the `software_title_id`. See [List software](#list-software) response payload for details about this object. +If `software_version_id` is specified, an additional top-level key `"software"` is returned with the software object corresponding to the `software_version_id`. See [List software versions](#list-software-versions) response payload for details about this object. -### Verify invite +If `additional_info_filters` is not specified, no `additional` information will be returned. -Verify the specified invite. +If `mdm_id` is specified, an additional top-level key `"mobile_device_management_solution"` is returned with the information corresponding to the `mdm_id`. -`GET /api/v1/fleet/invites/:token` +If `mdm_id`, `mdm_name`, `mdm_enrollment_status`, `os_settings`, or `os_settings_disk_encryption` is specified, then Windows Servers are excluded from the results. -#### Parameters +If `munki_issue_id` is specified, an additional top-level key `munki_issue` is returned with the information corresponding to the `munki_issue_id`. -| Name | Type | In | Description | -| ----- | ------- | ---- | -------------------------------------- | -| token | integer | path | **Required.** The user's invite token. | +If `after` is being used with `created_at` or `updated_at`, the table must be specified in `order_key`. Those columns become `h.created_at` and `h.updated_at`. #### Example -`GET /api/v1/fleet/invites/abcdef012456789` - -##### Default response - -`Status: 200` - -```json -{ - "invite": { - "created_at": "2021-01-15T00:58:33Z", - "updated_at": "2021-01-15T00:58:33Z", - "id": 4, - "email": "steve@example.com", - "name": "Steve", - "sso_enabled": false, - "global_role": "admin", - "teams": [] - } -} -``` - -##### Not found - -`Status: 404` - -```json -{ - "message": "Resource Not Found", - "errors": [ - { - "name": "base", - "reason": "Invite with token was not found in the datastore" - } - ] -} -``` - -### Update invite - -`PATCH /api/v1/fleet/invites/:id` - -#### Parameters - -| Name | Type | In | Description | -| ----------- | ------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| global_role | string | body | Role the user will be granted. Either a global role is needed, or a team role. | -| email | string | body | The email of the invited user. Updates on the email won't resend the invitation. | -| name | string | body | The name of the invited user. | -| sso_enabled | boolean | body | Whether or not SSO will be enabled for the invited user. | -| teams | array | body | _Available in Fleet Premium_. A list of the teams the user is a member of. Each item includes the team's ID and the user's role in the specified team. | - -#### Example - -`PATCH /api/v1/fleet/invites/123` - -##### Request body - -```json -{ - "email": "john_appleseed@example.com", - "name": "John", - "sso_enabled": false, - "global_role": null, - "teams": [ - { - "id": 2, - "role": "observer" - }, - { - "id": 3, - "role": "maintainer" - } - ] -} -``` - -##### Default response - -`Status: 200` - -```json -{ - "invite": { - "created_at": "0001-01-01T00:00:00Z", - "updated_at": "0001-01-01T00:00:00Z", - "id": 3, - "invited_by": 1, - "email": "john_appleseed@example.com", - "name": "John", - "sso_enabled": false, - "teams": [ - { - "id": 10, - "created_at": "0001-01-01T00:00:00Z", - "name": "Apples", - "description": "", - "agent_options": null, - "user_count": 0, - "host_count": 0, - "role": "observer" - }, - { - "id": 14, - "created_at": "0001-01-01T00:00:00Z", - "name": "Best of the Best Engineering", - "description": "", - "agent_options": null, - "user_count": 0, - "host_count": 0, - "role": "maintainer" - } - ] - } -} -``` - -### Version - -Get version and build information from the Fleet server. - -`GET /api/v1/fleet/version` - -#### Parameters - -None. - -#### Example - -`GET /api/v1/fleet/version` - -##### Default response - -`Status: 200` - -```json -{ - "version": "3.9.0-93-g1b67826f-dirty", - "branch": "version", - "revision": "1b67826fe4bf40b2f45ec53e01db9bf467752e74", - "go_version": "go1.15.7", - "build_date": "2021-03-27", - "build_user": "zwass" -} -``` - ---- - -## Hosts - -- [On the different timestamps in the host data structure](#on-the-different-timestamps-in-the-host-data-structure) -- [List hosts](#list-hosts) -- [Count hosts](#count-hosts) -- [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) -- [Transfer hosts to a team by filter](#transfer-hosts-to-a-team-by-filter) -- [Turn off MDM for a host](#turn-off-mdm-for-a-host) -- [Bulk delete hosts by filter or ids](#bulk-delete-hosts-by-filter-or-ids) -- [Get human-device mapping](#get-human-device-mapping) -- [Update custom human-device mapping](#update-custom-human-device-mapping) -- [Get host's device health report](#get-hosts-device-health-report) -- [Get host's mobile device management (MDM) information](#get-hosts-mobile-device-management-mdm-information) -- [Get mobile device management (MDM) summary](#get-mobile-device-management-mdm-summary) -- [Get host's mobile device management (MDM) and Munki information](#get-hosts-mobile-device-management-mdm-and-munki-information) -- [Get aggregated host's mobile device management (MDM) and Munki information](#get-aggregated-hosts-macadmin-mobile-device-management-mdm-and-munki-information) -- [Get host's scripts](#get-hosts-scripts) -- [Get host's software](#get-hosts-software) -- [Get hosts report in CSV](#get-hosts-report-in-csv) -- [Get host's disk encryption key](#get-hosts-disk-encryption-key) -- [Lock host](#lock-host) -- [Unlock host](#unlock-host) -- [Wipe host](#wipe-host) -- [Get host's past activity](#get-hosts-past-activity) -- [Get host's upcoming activity](#get-hosts-upcoming-activity) -- [Add labels to host](#add-labels-to-host) -- [Remove labels from host](#remove-labels-from-host) -- [Live query one host (ad-hoc)](#live-query-one-host-ad-hoc) -- [Live query host by identifier (ad-hoc)](#live-query-host-by-identifier-ad-hoc) - -### On the different timestamps in the host data structure - -Hosts have a set of timestamps usually named with an "_at" suffix, such as created_at, enrolled_at, etc. Before we go -through each of them and what they mean, we need to understand a bit more about how the host data structure is -represented in the database. - -The table `hosts` is the main one. It holds the core data for a host. A host doesn't exist if there is no row for it in -this table. This table also holds most of the timestamps, but it doesn't hold all of the host data. This is an important -detail as we'll see below. - -There's adjacent tables to this one that usually follow the name convention `host_`. Examples of -this are: `host_additional` that holds additional query results, `host_software` that links a host with many rows from -the `software` table. - -- `created_at`: the time the row in the database was created, which usually corresponds to the first enrollment of the host. -- `updated_at`: the last time the row in the database for the `hosts` table was updated. -- `detail_updated_at`: the last time Fleet updated host data, based on the results from the detail queries (this includes updates to host associated tables, e.g. `host_users`). -- `label_updated_at`: the last time Fleet updated the label membership for the host based on the results from the queries ran. -- `last_enrolled_at`: the last time the host enrolled to Fleet. -- `policy_updated_at`: the last time we updated the policy results for the host based on the queries ran. -- `seen_time`: the last time the host contacted the fleet server, regardless of what operation it was for. -- `software_updated_at`: the last time software changed for the host in any way. -- `last_restarted_at`: the last time that the host was restarted. - -### List hosts - -`GET /api/v1/fleet/hosts` - -#### Parameters - -| Name | Type | In | Description | -| ----------------------- | ------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| page | integer | query | Page number of the results to fetch. | -| per_page | integer | query | Results per page. | -| order_key | string | query | What to order results by. Can be any column in the hosts table. | -| after | string | query | The value to get results after. This needs `order_key` defined, as that's the column that would be used. **Note:** Use `page` instead of `after` | -| order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include 'asc' and 'desc'. Default is 'asc'. | -| status | string | query | Indicates the status of the hosts to return. Can either be 'new', 'online', 'offline', 'mia' or 'missing'. | -| query | string | query | Search query keywords. Searchable fields include `hostname`, `hardware_serial`, `uuid`, `ipv4` and the hosts' email addresses (only searched if the query looks like an email address, i.e. contains an '@', no space, etc.). | -| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's `additional` object. | -| team_id | integer | query | _Available in Fleet Premium_. Filters to only include hosts in the specified team. Use `0` to filter by hosts assigned to "No team". | -| policy_id | integer | query | The ID of the policy to filter hosts by. | -| policy_response | string | query | **Requires `policy_id`**. Valid options are 'passing' or 'failing'. | -| software_version_id | integer | query | The ID of the software version to filter hosts by. | -| software_title_id | integer | query | The ID of the software title to filter hosts by. | -| software_status | string | query | The status of the software install to filter hosts by. | -| os_version_id | integer | query | The ID of the operating system version to filter hosts by. | -| os_name | string | query | The name of the operating system to filter hosts by. `os_version` must also be specified with `os_name` | -| os_version | string | query | The version of the operating system to filter hosts by. `os_name` must also be specified with `os_version` | -| vulnerability | string | query | The cve to filter hosts by (including "cve-" prefix, case-insensitive). | -| device_mapping | boolean | query | Indicates whether `device_mapping` should be included for each host. See ["Get host's Google Chrome profiles](#get-hosts-google-chrome-profiles) for more information about this feature. | -| mdm_id | integer | query | The ID of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider and URL). | -| mdm_name | string | query | The name of the _mobile device management_ (MDM) solution to filter hosts by (that is, filter hosts that use a specific MDM provider). | -| mdm_enrollment_status | string | query | The _mobile device management_ (MDM) enrollment status to filter hosts by. Valid options are 'manual', 'automatic', 'enrolled', 'pending', or 'unenrolled'. | -| connected_to_fleet | boolean | query | Filter hosts that are talking to this Fleet server for MDM features. In rare cases, hosts can be enrolled to one Fleet server but talk to a different Fleet server for MDM features. In this case, the value would be `false`. Always `false` for Linux hosts. | -| macos_settings | string | query | Filters the hosts by the status of the _mobile device management_ (MDM) profiles applied to hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** | -| munki_issue_id | integer | query | The ID of the _munki issue_ (a Munki-reported error or warning message) to filter hosts by (that is, filter hosts that are affected by that corresponding error or warning message). | -| low_disk_space | integer | query | _Available in Fleet Premium_. Filters the hosts to only include hosts with less GB of disk space available than this value. Must be a number between 1-100. | -| disable_failing_policies| boolean | query | If `true`, hosts will return failing policies as 0 regardless of whether there are any that failed for the host. This is meant to be used when increased performance is needed in exchange for the extra information. | -| macos_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. | -| bootstrap_package | string | query | _Available in Fleet Premium_. Filters the hosts by the status of the MDM bootstrap package on the host. Valid options are 'installed', 'pending', or 'failed'. | -| os_settings | string | query | Filters the hosts by the status of the operating system settings applied to the hosts. Valid options are 'verified', 'verifying', 'pending', or 'failed'. **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** | -| os_settings_disk_encryption | string | query | Filters the hosts by disk encryption status. Valid options are 'verified', 'verifying', 'action_required', 'enforcing', 'failed', or 'removing_enforcement'. **Note: If this filter is used in Fleet Premium without a team ID filter, the results include only hosts that are not assigned to any team.** | -| populate_software | string | query | If `false` (or omitted), omits installed software details for each host. If `"without_vulnerability_details"`, include a list of installed software for each host, including which CVEs apply to the installed software versions. `true` adds vulnerability description, CVSS score, and other details when using Fleet Premium. See notes below on performance. | -| populate_policies | boolean | query | If `true`, the response will include policy data for each host. | - -> `software_id` is deprecated as of Fleet 4.42. It is maintained for backwards compatibility. Please use the `software_version_id` instead. - -> `populate_software` returns a lot of data per host when set, and drastically more data when set to `true` on Fleet Premium. If you need vulnerability details for a large number of hosts, consider setting `populate_software` to `without_vulnerability_details` and pulling vulnerability details from the [Get vulnerability](#get-vulnerability) endpoint, as this returns details once per vulnerability rather than once per vulnerability per host. - -If `software_title_id` is specified, an additional top-level key `"software_title"` is returned with the software title object corresponding to the `software_title_id`. See [List software](#list-software) response payload for details about this object. - -If `software_version_id` is specified, an additional top-level key `"software"` is returned with the software object corresponding to the `software_version_id`. See [List software versions](#list-software-versions) response payload for details about this object. - -If `additional_info_filters` is not specified, no `additional` information will be returned. - -If `mdm_id` is specified, an additional top-level key `"mobile_device_management_solution"` is returned with the information corresponding to the `mdm_id`. - -If `mdm_id`, `mdm_name`, `mdm_enrollment_status`, `os_settings`, or `os_settings_disk_encryption` is specified, then Windows Servers are excluded from the results. - -If `munki_issue_id` is specified, an additional top-level key `munki_issue` is returned with the information corresponding to the `munki_issue_id`. - -If `after` is being used with `created_at` or `updated_at`, the table must be specified in `order_key`. Those columns become `h.created_at` and `h.updated_at`. - -#### Example - -`GET /api/v1/fleet/hosts?page=0&per_page=100&order_key=hostname&query=2ce&populate_software=true&populate_policies=true` - -##### Request query parameters - -```json -{ - "page": 0, - "per_page": 100, - "order_key": "hostname" -} -``` +`GET /api/v1/fleet/hosts?page=0&per_page=100&order_key=hostname&query=2ce&populate_software=true&populate_policies=true` + +##### Request query parameters + +```json +{ + "page": 0, + "per_page": 100, + "order_key": "hostname" +} +``` ##### Default response @@ -11129,8 +10845,13 @@ Transforms a host name into a host id. For example, the Fleet UI use this endpoi - [Require password reset](#require-password-reset) - [List a user's sessions](#list-a-users-sessions) - [Delete a user's sessions](#delete-a-users-sessions) +- [Create invite](#create-invite) +- [List invites](#list-invites) +- [Delete invite](#delete-invite) +- [Verify invite](#verify-invite) +- [Modify invite](#modify-invite) -The Fleet server exposes a handful of API endpoints that handles common user management operations. All the following endpoints require prior authentication meaning you must first log in successfully before calling any of the endpoints documented below. +The Fleet server exposes API endpoints that handles common user management operations, including managing emailed invites to new users. All of these endpoints require prior authentication, so you'll need to log in before calling any of the endpoints documented below. ### List all users @@ -11523,50 +11244,260 @@ Returns all information about a specific user. #### Example (modify a user's teams) -`PATCH /api/v1/fleet/users/2` +`PATCH /api/v1/fleet/users/2` + +##### Request body + +```json +{ + "teams": [ + { + "id": 1, + "role": "observer" + }, + { + "id": 2, + "role": "maintainer" + } + ] +} +``` + +##### Default response + +`Status: 200` + +```json +{ + "user": { + "created_at": "2021-02-03T16:11:06Z", + "updated_at": "2021-02-03T16:11:06Z", + "id": 2, + "name": "Jane Doe", + "email": "janedoe@example.com", + "enabled": true, + "force_password_reset": false, + "gravatar_url": "", + "sso_enabled": false, + "mfa_enabled": false, + "global_role": "admin", + "teams": [ + { + "id": 2, + "role": "observer" + }, + { + "id": 3, + "role": "maintainer" + } + ] + } +} +``` + +### Delete user + +Delete the specified user from Fleet. + +`DELETE /api/v1/fleet/users/:id` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | ---------------------------- | +| id | integer | path | **Required**. The user's id. | + +#### Example + +`DELETE /api/v1/fleet/users/3` + +##### Default response + +`Status: 200` + + +### Require password reset + +The selected user is logged out of Fleet and required to reset their password during the next attempt to log in. This also revokes all active Fleet API tokens for this user. Returns the user object. + +`POST /api/v1/fleet/users/:id/require_password_reset` + +#### Parameters + +| Name | Type | In | Description | +| ----- | ------- | ---- | ---------------------------------------------------------------------------------------------- | +| id | integer | path | **Required**. The user's id. | +| require | boolean | body | Whether or not the user is required to reset their password during the next attempt to log in. | + +#### Example + +`POST /api/v1/fleet/users/123/require_password_reset` + +##### Request body + +```json +{ + "require": true +} +``` + +##### Default response + +`Status: 200` + +```json +{ + "user": { + "created_at": "2021-02-23T22:23:34Z", + "updated_at": "2021-02-23T22:28:52Z", + "id": 2, + "name": "Jane Doe", + "email": "janedoe@example.com", + "force_password_reset": true, + "gravatar_url": "", + "mfa_enabled": false, + "sso_enabled": false, + "global_role": "observer", + "teams": [] + } +} +``` + +### List a user's sessions + +Returns a list of the user's sessions in Fleet. + +`GET /api/v1/fleet/users/:id/sessions` + +#### Parameters + +None. + +#### Example + +`GET /api/v1/fleet/users/1/sessions` + +##### Default response + +`Status: 200` + +```json +{ + "sessions": [ + { + "session_id": 2, + "user_id": 1, + "created_at": "2021-02-03T16:12:50Z" + }, + { + "session_id": 3, + "user_id": 1, + "created_at": "2021-02-09T23:40:23Z" + }, + { + "session_id": 6, + "user_id": 1, + "created_at": "2021-02-23T22:23:58Z" + } + ] +} +``` + +### Delete a user's sessions + +Deletes the selected user's sessions in Fleet. Also deletes the user's API token. + +`DELETE /api/v1/fleet/users/:id/sessions` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | ----------------------------------------- | +| id | integer | path | **Required**. The ID of the desired user. | + +#### Example + +`DELETE /api/v1/fleet/users/1/sessions` + +##### Default response + +`Status: 200` + +### Create invite + +`POST /api/v1/fleet/invites` + +#### Parameters + +| Name | Type | In | Description | +| ----------- | ------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| global_role | string | body | Role the user will be granted. Either a global role is needed, or a team role. | +| email | string | body | **Required.** The email of the invited user. This email will receive the invitation link. | +| name | string | body | **Required.** The name of the invited user. | +| sso_enabled | boolean | body | **Required.** Whether or not SSO will be enabled for the invited user. | +| mfa_enabled | boolean | body | _Available in Fleet Premium._ Whether or not the invited user must click a magic link emailed to them to log in, after they successfully enter their username and password. Users can have SSO or MFA enabled, but not both. | +| teams | array | body | _Available in Fleet Premium_. A list of the teams the user is a member of. Each item includes the team's ID and the user's role in the specified team. | + +#### Example ##### Request body ```json { + "email": "john_appleseed@example.com", + "name": "John", + "sso_enabled": false, + "mfa_enabled": false, + "global_role": null, "teams": [ { - "id": 1, + "id": 2, "role": "observer" }, { - "id": 2, + "id": 3, "role": "maintainer" } ] } ``` +`POST /api/v1/fleet/invites` + ##### Default response `Status: 200` ```json { - "user": { - "created_at": "2021-02-03T16:11:06Z", - "updated_at": "2021-02-03T16:11:06Z", - "id": 2, - "name": "Jane Doe", - "email": "janedoe@example.com", - "enabled": true, - "force_password_reset": false, - "gravatar_url": "", + "invite": { + "created_at": "0001-01-01T00:00:00Z", + "updated_at": "0001-01-01T00:00:00Z", + "id": 3, + "invited_by": 1, + "email": "john_appleseed@example.com", + "name": "John", "sso_enabled": false, "mfa_enabled": false, - "global_role": "admin", "teams": [ { - "id": 2, + "id": 10, + "created_at": "0001-01-01T00:00:00Z", + "name": "Apples", + "description": "", + "agent_options": null, + "user_count": 0, + "host_count": 0, "role": "observer" }, { - "id": 3, + "id": 14, + "created_at": "0001-01-01T00:00:00Z", + "name": "Best of the Best Engineering", + "description": "", + "agent_options": null, + "user_count": 0, + "host_count": 0, "role": "maintainer" } ] @@ -11574,87 +11505,93 @@ Returns all information about a specific user. } ``` -### Delete user +### List invites -Delete the specified user from Fleet. +Returns a list of the active invitations in Fleet. -`DELETE /api/v1/fleet/users/:id` +`GET /api/v1/fleet/invites` #### Parameters -| Name | Type | In | Description | -| ---- | ------- | ---- | ---------------------------- | -| id | integer | path | **Required**. The user's id. | +| Name | Type | In | Description | +| --------------- | ------ | ----- | ----------------------------------------------------------------------------------------------------------------------------- | +| order_key | string | query | What to order results by. Can be any column in the invites table. | +| order_direction | string | query | **Requires `order_key`**. The direction of the order given the order key. Options include `asc` and `desc`. Default is `asc`. | +| query | string | query | Search query keywords. Searchable fields include `name` and `email`. | #### Example -`DELETE /api/v1/fleet/users/3` +`GET /api/v1/fleet/invites` ##### Default response `Status: 200` +```json +{ + "invites": [ + { + "created_at": "0001-01-01T00:00:00Z", + "updated_at": "0001-01-01T00:00:00Z", + "id": 3, + "email": "john_appleseed@example.com", + "name": "John", + "sso_enabled": false, + "mfa_enabled": false, + "global_role": "admin", + "teams": [] + }, + { + "created_at": "0001-01-01T00:00:00Z", + "updated_at": "0001-01-01T00:00:00Z", + "id": 4, + "email": "bob_marks@example.com", + "name": "Bob", + "sso_enabled": false, + "mfa_enabled": false, + "global_role": "admin", + "teams": [] + } + ] +} +``` -### Require password reset +### Delete invite -The selected user is logged out of Fleet and required to reset their password during the next attempt to log in. This also revokes all active Fleet API tokens for this user. Returns the user object. +Delete the specified invite from Fleet. -`POST /api/v1/fleet/users/:id/require_password_reset` +`DELETE /api/v1/fleet/invites/:id` #### Parameters -| Name | Type | In | Description | -| ----- | ------- | ---- | ---------------------------------------------------------------------------------------------- | -| id | integer | path | **Required**. The user's id. | -| require | boolean | body | Whether or not the user is required to reset their password during the next attempt to log in. | +| Name | Type | In | Description | +| ---- | ------- | ---- | ---------------------------- | +| id | integer | path | **Required.** The user's id. | #### Example -`POST /api/v1/fleet/users/123/require_password_reset` - -##### Request body - -```json -{ - "require": true -} -``` +`DELETE /api/v1/fleet/invites/123` ##### Default response `Status: 200` -```json -{ - "user": { - "created_at": "2021-02-23T22:23:34Z", - "updated_at": "2021-02-23T22:28:52Z", - "id": 2, - "name": "Jane Doe", - "email": "janedoe@example.com", - "force_password_reset": true, - "gravatar_url": "", - "mfa_enabled": false, - "sso_enabled": false, - "global_role": "observer", - "teams": [] - } -} -``` -### List a user's sessions +### Verify invite -Returns a list of the user's sessions in Fleet. +Verify the specified invite. -`GET /api/v1/fleet/users/:id/sessions` +`GET /api/v1/fleet/invites/:token` #### Parameters -None. +| Name | Type | In | Description | +| ----- | ------- | ---- | -------------------------------------- | +| token | integer | path | **Required.** The user's invite token. | #### Example -`GET /api/v1/fleet/users/1/sessions` +`GET /api/v1/fleet/invites/abcdef012456789` ##### Default response @@ -11662,46 +11599,118 @@ None. ```json { - "sessions": [ - { - "session_id": 2, - "user_id": 1, - "created_at": "2021-02-03T16:12:50Z" - }, - { - "session_id": 3, - "user_id": 1, - "created_at": "2021-02-09T23:40:23Z" - }, + "invite": { + "created_at": "2021-01-15T00:58:33Z", + "updated_at": "2021-01-15T00:58:33Z", + "id": 4, + "email": "steve@example.com", + "name": "Steve", + "sso_enabled": false, + "mfa_enabled": false, + "global_role": "admin", + "teams": [] + } +} +``` + +##### Not found + +`Status: 404` + +```json +{ + "message": "Resource Not Found", + "errors": [ { - "session_id": 6, - "user_id": 1, - "created_at": "2021-02-23T22:23:58Z" + "name": "base", + "reason": "Invite with token was not found in the datastore" } ] } ``` -### Delete a user's sessions - -Deletes the selected user's sessions in Fleet. Also deletes the user's API token. +### Modify invite -`DELETE /api/v1/fleet/users/:id/sessions` +`PATCH /api/v1/fleet/invites/:id` #### Parameters -| Name | Type | In | Description | -| ---- | ------- | ---- | ----------------------------------------- | -| id | integer | path | **Required**. The ID of the desired user. | +| Name | Type | In | Description | +| ----------- | ------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| global_role | string | body | Role the user will be granted. Either a global role is needed, or a team role. | +| email | string | body | The email of the invited user. Updates on the email won't resend the invitation. | +| name | string | body | The name of the invited user. | +| sso_enabled | boolean | body | Whether or not SSO will be enabled for the invited user. | +| mfa_enabled | boolean | body | _Available in Fleet Premium._ Whether or not the invited user must click a magic link emailed to them to log in, after they successfully enter their username and password. Users can have SSO or MFA enabled, but not both. | +| teams | array | body | _Available in Fleet Premium_. A list of the teams the user is a member of. Each item includes the team's ID and the user's role in the specified team. | #### Example -`DELETE /api/v1/fleet/users/1/sessions` +`PATCH /api/v1/fleet/invites/123` + +##### Request body + +```json +{ + "email": "john_appleseed@example.com", + "name": "John", + "sso_enabled": false, + "mfa_enabled": false, + "global_role": null, + "teams": [ + { + "id": 2, + "role": "observer" + }, + { + "id": 3, + "role": "maintainer" + } + ] +} +``` ##### Default response `Status: 200` +```json +{ + "invite": { + "created_at": "0001-01-01T00:00:00Z", + "updated_at": "0001-01-01T00:00:00Z", + "id": 3, + "invited_by": 1, + "email": "john_appleseed@example.com", + "name": "John", + "sso_enabled": false, + "mfa_enabled": false, + "teams": [ + { + "id": 10, + "created_at": "0001-01-01T00:00:00Z", + "name": "Apples", + "description": "", + "agent_options": null, + "user_count": 0, + "host_count": 0, + "role": "observer" + }, + { + "id": 14, + "created_at": "0001-01-01T00:00:00Z", + "name": "Best of the Best Engineering", + "description": "", + "agent_options": null, + "user_count": 0, + "host_count": 0, + "role": "maintainer" + } + ] + } +} +``` + ## Debug - [Get a summary of errors](#get-a-summary-of-errors)