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 | 581 +++++++++++++++++++------------------- 1 file changed, 295 insertions(+), 286 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index c0cf0ac76f..fec0670a4a 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,285 +2084,6 @@ Delete all of a team's existing enroll secrets } ``` -### 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. | -| 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, - "global_role": null, - "teams": [ - { - "id": 2, - "role": "observer" - }, - { - "id": 3, - "role": "maintainer" - } - ] -} -``` - -`POST /api/v1/fleet/invites` - -##### 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" - } - ] - } -} -``` - -### 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`. | - -#### Example - -`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, - "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": [] - } - ] -} -``` - -### Delete invite - -Delete the specified invite from Fleet. - -`DELETE /api/v1/fleet/invites/:id` - -#### Parameters - -| Name | Type | In | Description | -| ---- | ------- | ---- | ---------------------------- | -| id | integer | path | **Required.** The user's id. | - -#### Example - -`DELETE /api/v1/fleet/invites/123` - -##### Default response - -`Status: 200` - - -### Verify invite - -Verify the specified invite. - -`GET /api/v1/fleet/invites/:token` - -#### Parameters - -| Name | Type | In | Description | -| ----- | ------- | ---- | -------------------------------------- | -| token | integer | path | **Required.** The user's invite token. | - -#### 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. @@ -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 @@ -11702,6 +11423,294 @@ Deletes the selected user's sessions in Fleet. Also deletes the user's API token `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": 2, + "role": "observer" + }, + { + "id": 3, + "role": "maintainer" + } + ] +} +``` + +`POST /api/v1/fleet/invites` + +##### 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" + } + ] + } +} +``` + +### 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`. | + +#### Example + +`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": [] + } + ] +} +``` + +### Delete invite + +Delete the specified invite from Fleet. + +`DELETE /api/v1/fleet/invites/:id` + +#### Parameters + +| Name | Type | In | Description | +| ---- | ------- | ---- | ---------------------------- | +| id | integer | path | **Required.** The user's id. | + +#### Example + +`DELETE /api/v1/fleet/invites/123` + +##### Default response + +`Status: 200` + + +### Verify invite + +Verify the specified invite. + +`GET /api/v1/fleet/invites/:token` + +#### Parameters + +| Name | Type | In | Description | +| ----- | ------- | ---- | -------------------------------------- | +| token | integer | path | **Required.** The user's invite token. | + +#### 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, + "mfa_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" + } + ] +} +``` + +### Modify 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. | +| 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 + +`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)