Skip to content

#38044 API design: Create API-only users that only have access to Customer-defined Fleet API endpoints #42352

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rachaelshaw merged 9 commits into from
Apr 23, 2026
Merged

#38044 API design: Create API-only users that only have access to Customer-defined Fleet API endpoints #42352

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
2300a17
Update rest-api.md
rachaelshaw Mar 24, 2026
a150b60
Apply suggestion from @rachaelshaw
rachaelshaw Mar 25, 2026
6b4716e
Apply suggestions from code review
rachaelshaw Mar 25, 2026
e2e0041
Apply suggestion from @rachaelshaw
rachaelshaw Mar 25, 2026
92230bb
Apply suggestion from @rachaelshaw
rachaelshaw Mar 25, 2026
62369aa
Apply suggestion from @rachaelshaw
rachaelshaw Mar 26, 2026
27fc20d
Apply suggestion from @lucasmrod
rachaelshaw Apr 3, 2026
734a5ea
Apply suggestion from @rachaelshaw
rachaelshaw Apr 13, 2026
30d4501
Apply suggestion from @rachaelshaw
rachaelshaw Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 124 additions & 0 deletions docs/REST API/rest-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12962,6 +12962,8 @@ 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)
Comment thread
rachaelshaw marked this conversation as resolved.

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.

Expand Down Expand Up @@ -13824,6 +13826,128 @@ Verify the specified invite.
}
```

### Create API-only user

Creates an API-only user that does not have access to the UI.
Copy link
Copy Markdown
Member

@lucasmrod lucasmrod Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe worth documenting that this is a global/team admin only endpoint.


`POST /api/v1/fleet/users/api_only`

| Name | Type | In | Description |
| :---------------------- | :------ | :---- | :---------- |
Comment thread
rachaelshaw marked this conversation as resolved.
| 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). |
Copy link
Copy Markdown
Member

@lucasmrod lucasmrod Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rachaelshaw
When omitted or empty it means access to ALL, right?

And on the UI we probably want to disable the Save button if the user selected Specific API endpoints but didn't choose any.

Copy link
Copy Markdown
Member Author

@rachaelshaw rachaelshaw Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cood catch 👍 We should make the user select at least one endpoint or "All" before saving
Would it match existing patterns to have this be null if not setting specific endpoints?

Copy link
Copy Markdown
Member Author

@rachaelshaw rachaelshaw Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^ @juan-fdz-hawa


If `api_endpoints` is specified, these do not grant additional permissions otherwise forbidden by the user's `role`.


#### Example

`POST /api/v1/fleet/users/api_only`

##### Request body

```json
{
"name": "Jane Doe",
"fleets": [
{
"id": 2,
"role": "observer"
},
{
"id": 3,
"role": "maintainer"
}
],
"api_endpoints": [1,5,7,32]
Copy link
Copy Markdown
Member

@lucasmrod lucasmrod Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rachaelshaw
I put as a goal on the implementation to make these ids "stable".
Meaning that for all users/customers the ids map to the same endpoints (to ease troubleshooting and reproducing issues).

}
```

##### 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",
Copy link
Copy Markdown
Contributor

@juan-fdz-hawa juan-fdz-hawa Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just double checking, janedoe is the name of the admin that's creating the API user? Or is the whole email randomly generated?

Copy link
Copy Markdown
Member Author

@rachaelshaw rachaelshaw Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah that's the admin's email

"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
Comment thread
rachaelshaw marked this conversation as resolved.

_Available in Fleet Premium._

Lists Fleet REST API endpoints that an API-only user can be granted access to.
Comment thread
rachaelshaw marked this conversation as resolved.

`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

`GET /api/v1/fleet/rest_api?query=get%20host%20by%20identifier`
Comment thread
rachaelshaw marked this conversation as resolved.
or
`GET /api/v1/fleet/rest_api?query=%2Fapi%2Fv1%2Ffleet%2Fhosts%2Fidentifier%2F%3Ahost_identifier`

##### Default response

`Status: 200`

```json
{
"api_endpoints": [
{
"id": 123,
"display_name": "Get host by identifier",
"method": "GET",
"path": "/api/v1/fleet/hosts/identifier/:identifier",
"deprecated": false
}
],
"meta": {
"has_next_results": true,
"has_previous_results": false
},
"count": 1
}
```

---

## Debug

- [Get errors](#get-errors)
Expand Down
Loading