From 2300a171c2eb55cffadcf672deeb835258cfb688 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Tue, 24 Mar 2026 18:07:53 -0500 Subject: [PATCH 1/9] Update rest-api.md --- docs/REST API/rest-api.md | 118 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 207012e647d..1d55b3da7ab 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -12962,6 +12962,7 @@ Transforms a host name into a host id. For example, the Fleet UI uses this endpo - [Delete invite](#delete-invite) - [Verify invite](#verify-invite) - [Update invite](#update-invite) +- [List API endpoints for API-only user permissions](#list-api-endpoints-for-api-only-user-permissions) 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. @@ -13824,6 +13825,123 @@ Verify the specified invite. } ``` +### Create API-only user + +Creates an API-only user that does not have access to the UI. + +`POST /api/v1/fleet/users/api_only` + +| Name | Type | In | Description | +| :---------------------- | :------ | :---- | :---------- | +| password | string | body | The user's password (required for non-SSO users). +| global_role | string | body | The role assigned to the user. If `global_role` is specified, `fleets` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). | +| fleets | array | body | _Available in Fleet Premium_. The fleets and respective roles assigned to the user. Should contain an array of objects in which each object includes the fleet's `id` and the user's `role` on each fleet. If `fleets` is specified, `global_role` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). | +| api_endpoints | array | body | _Available in Fleet Premium_. A list of `id`s of API endpoints this user will have access to. For available endpoints, see [List API endpoints for API-only user permissions](#list-api-endpoints-for-api-only-user-permissions). | + +If `api_endpoints` is specified, these do not grant additional permissions otherwise forbidden by the user's `role`. + + +#### Example + +`POST /api/v1/fleet/users/admin` + +##### Request body + +```json +{ + "name": "Jane Doe", + "fleets": [ + { + "id": 2, + "role": "observer" + }, + { + "id": 3, + "role": "maintainer" + } + ], + "api_endpoints": [1,5,7,32] +} +``` + +##### Default response + +`Status: 200` + +```json +{ + "user": { + "created_at": "0001-01-01T00:00:00Z", + "updated_at": "0001-01-01T00:00:00Z", + "id": 5, + "name": "Jane Doe", + "email": "janedoe+randomlygeneratedstring@example.com", + "enabled": true, + "force_password_reset": false, + "gravatar_url": "", + "sso_enabled": false, + "mfa_enabled": false, + "api_only": true, + "global_role": null, + "fleets": [ + { + "id": 2, + "role": "observer" + }, + { + "id": 3, + "role": "maintainer" + } + ], + "api_endpoints": [1,5,7,32] + }, + "token": "{API key}" +} +``` + + +### List API endpoints for API-only user permissions + +Lists Fleet REST API endpoints that an API-only user can be granted access to. + +`GET /api/v1/fleet/rest_api` + +| Name | Type | In | Description | +| :---------------------- | :------ | :---- | :---------- | +| query | string | query | Search query keywords. Searchable fields include `display_name` and `path`. | + +Searching by path ignores the naming of path parameters that are specified with `:` , e.g. `:id`. So searching `/hosts/:id/report` is the same as searching `/hosts/:host_id/report`. + +Experimental endpoints are excluded from the results, since they are not for use in automated workflows. + +#### Example + +`?query=get%20host%20by%20identifier` + +##### Default response + +`Status: 200` + +```json +{ + "api_endpoints": [ + { + "id": 123, + "display_name": "Get host by identifier", + "protocol": "GET", + "path": "" + } + ], + "meta": { + "has_next_results": true, + "has_previous_results": false + }, + "count": 1 +} +``` + +--- + ## Debug - [Get errors](#get-errors) From a150b60e25b1535650b22f1fef6edc6dfd003faf Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Wed, 25 Mar 2026 09:56:10 -0500 Subject: [PATCH 2/9] Apply suggestion from @rachaelshaw --- docs/REST API/rest-api.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 1d55b3da7ab..943877b14ca 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -12962,6 +12962,7 @@ Transforms a host name into a host id. For example, the Fleet UI uses this endpo - [Delete invite](#delete-invite) - [Verify invite](#verify-invite) - [Update invite](#update-invite) +- [Create API-only user](#create-api-only-user) - [List API endpoints for API-only user permissions](#list-api-endpoints-for-api-only-user-permissions) 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. From 6b4716ed8ae9a71f225e1192f164a6d46e705d09 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Wed, 25 Mar 2026 11:00:48 -0500 Subject: [PATCH 3/9] Apply suggestions from code review Co-authored-by: Rachael Shaw --- docs/REST API/rest-api.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 943877b14ca..917e641fead 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -13917,7 +13917,7 @@ Experimental endpoints are excluded from the results, since they are not for use #### Example -`?query=get%20host%20by%20identifier` +`GET /api/v1/fleet/rest_api?query=get%20host%20by%20identifier` ##### Default response @@ -13930,7 +13930,8 @@ Experimental endpoints are excluded from the results, since they are not for use "id": 123, "display_name": "Get host by identifier", "protocol": "GET", - "path": "" + "path": "", + "deprecated": false } ], "meta": { From e2e004177d8813b92f2a154091ab2cac20bbfe22 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Wed, 25 Mar 2026 11:02:55 -0500 Subject: [PATCH 4/9] Apply suggestion from @rachaelshaw --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 917e641fead..25d5962e9c6 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -13930,7 +13930,7 @@ Experimental endpoints are excluded from the results, since they are not for use "id": 123, "display_name": "Get host by identifier", "protocol": "GET", - "path": "", + "path": "/api/v1/fleet/hosts/identifier/:identifier", "deprecated": false } ], From 92230bb556e1e46e8220dbe23eb56600f2a428c7 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Wed, 25 Mar 2026 11:06:14 -0500 Subject: [PATCH 5/9] Apply suggestion from @rachaelshaw --- docs/REST API/rest-api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 25d5962e9c6..d49d0c961f1 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -13918,6 +13918,8 @@ Experimental endpoints are excluded from the results, since they are not for use #### Example `GET /api/v1/fleet/rest_api?query=get%20host%20by%20identifier` +or +`GET /api/v1/fleet/rest_api?query=%2Fapi%2Fv1%2Ffleet%2Fhosts%2Fidentifier%2F%3Ahost_identifier` ##### Default response From 62369aa37768463f4cc7b6fa0c77dc917f4d91a2 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Thu, 26 Mar 2026 16:38:18 -0500 Subject: [PATCH 6/9] Apply suggestion from @rachaelshaw --- docs/REST API/rest-api.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index d49d0c961f1..498c1315485 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -13903,6 +13903,8 @@ If `api_endpoints` is specified, these do not grant additional permissions other ### List API endpoints for API-only user permissions + _Available in Fleet Premium._ + Lists Fleet REST API endpoints that an API-only user can be granted access to. `GET /api/v1/fleet/rest_api` From 27fc20d7f017d32f5aad7719d8b4ff1999e50911 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Fri, 3 Apr 2026 18:38:00 -0500 Subject: [PATCH 7/9] Apply suggestion from @lucasmrod Co-authored-by: Lucas Manuel Rodriguez --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 498c1315485..ec9e570ff35 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -13844,7 +13844,7 @@ If `api_endpoints` is specified, these do not grant additional permissions other #### Example -`POST /api/v1/fleet/users/admin` +`POST /api/v1/fleet/users/api_only` ##### Request body From 734a5eaabc5a6a5d96d576cb1eb5cfc0cf60e19c Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Mon, 13 Apr 2026 11:51:28 -0500 Subject: [PATCH 8/9] Apply suggestion from @rachaelshaw --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index ec9e570ff35..1ea80170b7a 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -13933,7 +13933,7 @@ or { "id": 123, "display_name": "Get host by identifier", - "protocol": "GET", + "method": "GET", "path": "/api/v1/fleet/hosts/identifier/:identifier", "deprecated": false } From 30d4501af44f14f2bb6763814adc9cfddbf98a38 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Mon, 13 Apr 2026 12:05:26 -0500 Subject: [PATCH 9/9] Apply suggestion from @rachaelshaw --- docs/REST API/rest-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index 1ea80170b7a..3a2bc056a4b 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -13834,7 +13834,7 @@ Creates an API-only user that does not have access to the UI. | Name | Type | In | Description | | :---------------------- | :------ | :---- | :---------- | -| password | string | body | The user's password (required for non-SSO users). +| name | string | body | The display name for the API-only user. | | global_role | string | body | The role assigned to the user. If `global_role` is specified, `fleets` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). | | fleets | array | body | _Available in Fleet Premium_. The fleets and respective roles assigned to the user. Should contain an array of objects in which each object includes the fleet's `id` and the user's `role` on each fleet. If `fleets` is specified, `global_role` cannot be specified. For more information, see [manage access](https://fleetdm.com/docs/using-fleet/manage-access). | | api_endpoints | array | body | _Available in Fleet Premium_. A list of `id`s of API endpoints this user will have access to. For available endpoints, see [List API endpoints for API-only user permissions](#list-api-endpoints-for-api-only-user-permissions). |