From dd7d5cd9a319cee4551f2b904798ca75961689b8 Mon Sep 17 00:00:00 2001 From: noahtalerman <47070608+noahtalerman@users.noreply.github.com> Date: Tue, 9 Mar 2021 07:50:48 -0800 Subject: [PATCH] Add sessions, reset_password, and more endpoints to REST API docs (#382) This PR is part of the Complete documentation for Fleet API project #43. The endpoint included in these changes: - POST /api/v1/fleet/reset_password - GET /api/v1/fleet/sessions/{id} - DELETE /api/v1/fleet/sessions/{id} - POST /api/v1/fleet/queries/delete - GET /api/v1/fleet/email/change/{token} --- docs/1-Using-Fleet/3-REST-API.md | 169 ++++++++++++++++++++++++++++++- 1 file changed, 166 insertions(+), 3 deletions(-) diff --git a/docs/1-Using-Fleet/3-REST-API.md b/docs/1-Using-Fleet/3-REST-API.md index 64ef720c8..e363e5ceb 100644 --- a/docs/1-Using-Fleet/3-REST-API.md +++ b/docs/1-Using-Fleet/3-REST-API.md @@ -6,6 +6,7 @@ - [Hosts](#hosts) - [Labels](#labels) - [Users](#users) +- [Sessions](#sessions) - [Queries](#queries) - [Packs](#packs) - [Targets](#targets) @@ -58,6 +59,7 @@ All of these objects are put together and distributed to the appropriate osquery - [Log out](#log-out) - [Forgot password](#forgot-password) - [Change password](#change-password) +- [Reset password](#reset-password) - [Me](#me) - [SSO config](#sso-config) - [Initiate SSO](#initiate-sso) @@ -252,6 +254,42 @@ Changes the password for the authenticated user. } ``` +### Reset password + +Resets a user's password. Which user is determined by the password reset token used. The password reset token can be found in the password reset email sent to the desired user. + +`POST /api/v1/fleet/reset_password` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ----- | ---------------------------- | +| new_password | string | body | **Required**. The new password. | +| new_password_confirmation | string | body | **Required**. Confirmation for the new password. | +| password_reset_token | string | body | **Required**. The token provided to the user in the password reset email. | + +#### Example + +`POST /api/v1/fleet/reset_password` + +##### Request body + +``` +{ + "new_password": "abc123" + "new_password_confirmation": "abc123" + "password_reset_token": "UU5EK0JhcVpsRkY3NTdsaVliMEZDbHJ6TWdhK3oxQ1Q=" +} +``` + +##### Default response + +`Status: 200` + +``` +{} +``` + --- ### Me @@ -1709,7 +1747,7 @@ The selected user is logged out of Fleet and required to reset their password du `POST /api/v1/fleet/users/{id}/require_password_reset` -#### Request body +##### Request body ``` { @@ -1787,12 +1825,73 @@ Deletes the selected user's sessions in Fleet. Also deletes the user's API token #### Parameters -None. +| 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` + +``` +{} +``` + +--- + +## Sessions +- [Get session info](#get-sessions-info) +- [Delete session](#delete-session) + +### Get session info + +Returns the session information for the session specified by ID. + +`GET /api/v1/fleet/sessions/{id}` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| id | integer | path | **Required**. The ID of the desired session. | + +#### Example + +`GET /api/v1/fleet/sessions/1` + +##### Default response + +`Status: 200` + +``` +{ + "session_id": 1, + "user_id": 1, + "created_at": "2021-03-02T18:41:34Z" +} +``` + +### Delete session + +Deletes the session specified by ID. When the user associated with the session next attempts to access Fleet, they will be asked to log in. + +`DELETE /api/v1/fleet/sessions/{id}` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| id | integer | path | **Required**. The id of the desired session. | + +#### Example + +`DELETE /api/v1/fleet/sessions/1` + + ##### Default response `Status: 200` @@ -1811,6 +1910,7 @@ None. - [Modify query](#modify-query) - [Delete query](#delete-query) - [Delete query by ID](#delete-query-by-id) +- [Delete queries](#delete-queries) - [Get queries specs](#get-queries-specs) - [Get query spec](#get-query-spec) - [Apply queries specs](#apply-queries-specs) @@ -2113,6 +2213,42 @@ Deletes the query specified by ID. {} ``` +### Delete queries + +Deletes the queries specified by ID. Returns the count of queries successfully deleted. + +`POST /api/v1/fleet/queries/delete` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| ids | list | body | **Required.** The IDs of the queries. | + +#### Example + +`POST /api/v1/fleet/queries/delete` + +##### Request body + +``` +{ + "ids": [ + 2, 24, 25 + ] +} +``` + +##### Default response + +`Status: 200` + +``` +{ + "deleted": 3 +} +``` + ### Get queries specs Returns a list of all queries in the Fleet instance. Each item returned includes the name, description, and SQL of the query. @@ -4008,7 +4144,7 @@ Verify the specified invite. | Name | Type | In | Description | | ---------- | ------- | ---- | ------------------------------------------------ | -| token | integer | path | **Required.** The user's invite token. | +| token | integer | path | **Required.** Token provided to the user in the invitation email.| #### Example @@ -4049,6 +4185,33 @@ Verify the specified invite. ] } ``` + +### Change email + +Changes the email specified by token. + +`GET /api/v1/fleet/email/change/{token}` + +#### Parameters + +| Name | Type | In | Description | +| ---------- | ------- | ---- | ------------------------------------------------ | +| token | integer | path | **Required.** The token provided to the user in the email change confirmation email.| + +#### Example + +`GET /api/v1/fleet/invites/{token}` + + +##### Default response + +`Status: 200` + +``` +{ + "new_email": janedoe@example.com +} +``` --- ## Osquery options