mirror of
https://github.com/fleetdm/fleet
synced 2026-05-23 17:08:53 +00:00
Add documentation for authentication API endpoints (#44)
Endpoints that have been added: - /api/v1/kolide/login POST - /api/v1/kolide/logout POST - /api/v1/kolide/forgot_password POST - /api/v1/kolide/me GET - /api/v1/kolide/change_password POST - /api/v1/kolide/perform_required_password_reset POST - /api/v1/kolide/sso POST - /api/v1/kolide/sso GET
This commit is contained in:
noahtalerman
GitHub
parent
f62dc055ee
commit
32f466d6c0
1 changed files with 475 additions and 12 deletions
|
|
@ -1,24 +1,64 @@
|
|||
# Fleet REST API endpoints
|
||||
|
||||
## Hosts
|
||||
## Authentication
|
||||
|
||||
### List hosts
|
||||
Making authenticated requests to the Fleet server requires that you are granted permission to access data. The Fleet Authentication API enables you to receive an authorization token.
|
||||
|
||||
All Fleet API requests are authenticated unless noted in the documentation. This means that almost all Fleet API requests will require sending the authentication token in the request header.
|
||||
|
||||
The typical steps to making an authenticated API request are outlined below.
|
||||
|
||||
First, utilize the `/login` endpoint to receive an authentication token.
|
||||
|
||||
`POST /api/v1/kolide/login`
|
||||
|
||||
Request body
|
||||
|
||||
```
|
||||
{
|
||||
username: "janedoe@example.com"
|
||||
passsword: "VArCjNW7CfsxGp67"
|
||||
}
|
||||
```
|
||||
|
||||
Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
```
|
||||
{
|
||||
"user": {
|
||||
"created_at": "2020-11-13T22:57:12Z",
|
||||
"updated_at": "2020-11-13T22:57:12Z",
|
||||
"id": 1,
|
||||
"username": "jane",
|
||||
"name": "",
|
||||
"email": "janedoe@example.com",
|
||||
"admin": true,
|
||||
"enabled": true,
|
||||
"force_password_reset": false,
|
||||
"gravatar_url": "",
|
||||
"sso_enabled": false
|
||||
},
|
||||
"token": "{your token}"
|
||||
}
|
||||
```
|
||||
|
||||
Then, use the token returned from the `/login` endpoint to authenticate further API requests. The example below utilizes the `/hosts` endpoint.
|
||||
|
||||
`GET /api/v1/kolide/hosts`
|
||||
|
||||
Parameters
|
||||
Request header
|
||||
|
||||
| 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. |
|
||||
| status | string | query | Indicates the status of the hosts to return. Can either be `new`, `online`, `offline`, or `mia`.|
|
||||
| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](https://github.com/fleetdm/fleet/blob/master/docs/cli/file-format.md#fleet-configuration-options) for an example configuration with hosts' additional information.|
|
||||
```
|
||||
{
|
||||
"authentication": "Bearer {your token}"
|
||||
}
|
||||
```
|
||||
|
||||
Example
|
||||
Default response
|
||||
|
||||
`GET /api/v1/kolide/hosts?page=0&per_page=100&order_key=host_name`
|
||||
`Status: 200`
|
||||
|
||||
```
|
||||
{
|
||||
|
|
@ -100,3 +140,426 @@ Example
|
|||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Log in
|
||||
|
||||
Authenticates the user with the specified credentials. Use the token returned from this endpoint to authenticate further API requests.
|
||||
|
||||
`POST /api/v1/kolide/login`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | In | Description |
|
||||
|-------------------------|---------|-------|---------------------------------------------------|
|
||||
| username | string | body | **Required**. The user's email. |
|
||||
| password | string | body | **Required**. The user's plain text password.|
|
||||
|
||||
#### Example
|
||||
|
||||
`POST /api/v1/kolide/login`
|
||||
|
||||
##### Request body
|
||||
|
||||
```
|
||||
{
|
||||
username: "janedoe@example.com"
|
||||
passsword: "VArCjNW7CfsxGp67"
|
||||
}
|
||||
```
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
```
|
||||
{
|
||||
"user": {
|
||||
"created_at": "2020-11-13T22:57:12Z",
|
||||
"updated_at": "2020-11-13T22:57:12Z",
|
||||
"id": 1,
|
||||
"username": "jane",
|
||||
"name": "",
|
||||
"email": "janedoe@example.com",
|
||||
"admin": true,
|
||||
"enabled": true,
|
||||
"force_password_reset": false,
|
||||
"gravatar_url": "",
|
||||
"sso_enabled": false
|
||||
},
|
||||
"token": "{your token}"
|
||||
}
|
||||
```
|
||||
*******
|
||||
|
||||
|
||||
### Log out
|
||||
|
||||
Logs out the authenticated user.
|
||||
|
||||
`POST /api/v1/kolide/logout`
|
||||
|
||||
#### Example
|
||||
|
||||
`POST /api/v1/kolide/logout`
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
*******
|
||||
|
||||
|
||||
### Forgot password
|
||||
|
||||
Sends a password reset email to the specified email. Requires that SMTP is configured for your Fleet server.
|
||||
|
||||
`POST /api/v1/kolide/forgot_password`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | In | Description |
|
||||
|-------------------------|---------|--------|---------------------------------------------------------------------------|
|
||||
| email | string | body | **Required**. The email of the user requesting the reset password link. |
|
||||
|
||||
#### Example
|
||||
|
||||
`POST /api/v1/kolide/forgot_password`
|
||||
|
||||
##### Request body
|
||||
|
||||
```
|
||||
{
|
||||
"email": "janedoe@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
##### Unknown error
|
||||
|
||||
`Status: 500`
|
||||
|
||||
```
|
||||
{
|
||||
"message": "Unknown Error",
|
||||
"errors": [
|
||||
{
|
||||
"name": "base",
|
||||
"reason": "email not configured",
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
*******
|
||||
|
||||
|
||||
### Change password
|
||||
|
||||
`POST /api/v1/kolide/change_password`
|
||||
|
||||
Changes the password for the authenticated user.
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | In | Description |
|
||||
|-------------------------|---------|----------|-----------------------------------------------------------------------------|
|
||||
| old_password | string | body | **Required**. The user's old password. |
|
||||
| new_password | string | body | **Required**. The user's new password. |
|
||||
|
||||
#### Example
|
||||
|
||||
`POST /api/v1/kolide/change_password`
|
||||
|
||||
##### Request body
|
||||
|
||||
```
|
||||
{
|
||||
"old_password": "VArCjNW7CfsxGp67",
|
||||
"new_password": "zGq7mCLA6z4PzArC",
|
||||
}
|
||||
```
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
##### Validation failed
|
||||
|
||||
`Status: 422 Unprocessable entity`
|
||||
|
||||
```
|
||||
{
|
||||
"message": "Validation Failed",
|
||||
"errors": [
|
||||
{
|
||||
"name": "old_password",
|
||||
"reason": "old password does not match"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
*******
|
||||
|
||||
|
||||
### Me
|
||||
|
||||
Retrieves the user data for the authenticated user.
|
||||
|
||||
`POST /api/v1/kolide/me`
|
||||
|
||||
#### Example
|
||||
|
||||
`POST /api/v1/kolide/me`
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
```
|
||||
{
|
||||
"user": {
|
||||
"created_at": "2020-11-13T22:57:12Z",
|
||||
"updated_at": "2020-11-16T23:49:41Z",
|
||||
"id": 1,
|
||||
"username": "jane",
|
||||
"name": "",
|
||||
"email": "janedoe@example.com",
|
||||
"admin": true,
|
||||
"enabled": true,
|
||||
"force_password_reset": false,
|
||||
"gravatar_url": "",
|
||||
"sso_enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
*******
|
||||
|
||||
|
||||
### Perform required password reset
|
||||
|
||||
Resets the password of the authenticated user. Requires that `force_password_reset` is set to `true` prior to the request.
|
||||
|
||||
`POST /api/v1/kolide/perform_require_password_reset`
|
||||
|
||||
#### Example
|
||||
|
||||
`POST /api/v1/kolide/perform_required_password_reset`
|
||||
|
||||
##### Request body
|
||||
|
||||
```
|
||||
{
|
||||
"new_password": "sdPz8CV5YhzH47nK"
|
||||
}
|
||||
```
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
```
|
||||
{
|
||||
"user": {
|
||||
"created_at": "2020-11-13T22:57:12Z",
|
||||
"updated_at": "2020-11-17T00:09:23Z",
|
||||
"id": 1,
|
||||
"username": "jane",
|
||||
"name": "",
|
||||
"email": "janedoe@example.com",
|
||||
"admin": true,
|
||||
"enabled": true,
|
||||
"force_password_reset": false,
|
||||
"gravatar_url": "",
|
||||
"sso_enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
*******
|
||||
|
||||
|
||||
### SSO config
|
||||
|
||||
Gets the current SSO configuration.
|
||||
|
||||
`GET /api/v1/kolide/sso`
|
||||
|
||||
#### Example
|
||||
|
||||
`GET /api/v1/kolide/sso`
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
```
|
||||
{
|
||||
"settings": {
|
||||
"idp_name": "IDP Vendor 1",
|
||||
"idp_image_url": "",
|
||||
"sso_enabled": false
|
||||
}
|
||||
}
|
||||
```
|
||||
*******
|
||||
|
||||
|
||||
### Initiate SSO
|
||||
|
||||
`POST /api/v1/kolide/sso`
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Name | Type | In | Description |
|
||||
|-------------------------|---------|----------|-----------------------------------------------------------------------------|
|
||||
| relay_url | string | body | **Required**. The relative url to be navigated to after succesful sign in. |
|
||||
|
||||
#### Example
|
||||
|
||||
`POST /api/v1/kolide/sso`
|
||||
|
||||
##### Request body
|
||||
|
||||
```
|
||||
{
|
||||
"relay_url": "/hosts/manage"
|
||||
}
|
||||
```
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
##### Unknown error
|
||||
|
||||
`Status: 500`
|
||||
|
||||
```
|
||||
{
|
||||
"message": "Unknown Error",
|
||||
"errors": [
|
||||
{
|
||||
"name": "base",
|
||||
"reason": "InitiateSSO getting metadata: Get \"https://idp.example.org/idp-meta.xml\": dial tcp: lookup idp.example.org on [2001:558:feed::1]:53: no such host"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
*******
|
||||
|
||||
|
||||
## Hosts
|
||||
|
||||
### List hosts
|
||||
|
||||
`GET /api/v1/kolide/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. |
|
||||
| status | string | query | Indicates the status of the hosts to return. Can either be `new`, `online`, `offline`, or `mia`.|
|
||||
| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](https://github.com/fleetdm/fleet/blob/master/docs/cli/file-format.md#fleet-configuration-options) for an example configuration with hosts' additional information.|
|
||||
|
||||
#### Example
|
||||
|
||||
`GET /api/v1/kolide/hosts?page=0&per_page=100&order_key=host_name`
|
||||
|
||||
##### Request query parameters
|
||||
|
||||
```
|
||||
{
|
||||
"page": 0,
|
||||
"per_page": 100,
|
||||
"order_key": "host_name",
|
||||
}
|
||||
```
|
||||
|
||||
##### Default response
|
||||
|
||||
`Status: 200`
|
||||
|
||||
```
|
||||
{
|
||||
"hosts": [
|
||||
{
|
||||
"created_at": "2020-11-05T05:09:44Z",
|
||||
"updated_at": "2020-11-05T06:03:39Z",
|
||||
"id": 1,
|
||||
"detail_updated_at": "2020-11-05T05:09:45Z",
|
||||
"label_updated_at": "2020-11-05T05:14:51Z",
|
||||
"seen_time": "2020-11-05T06:03:39Z",
|
||||
"hostname": "2ceca32fe484",
|
||||
"uuid": "392547dc-0000-0000-a87a-d701ff75bc65",
|
||||
"platform": "centos",
|
||||
"osquery_version": "2.7.0",
|
||||
"os_version": "CentOS Linux 7",
|
||||
"build": "",
|
||||
"platform_like": "rhel fedora",
|
||||
"code_name": "",
|
||||
"uptime": 8305000000000,
|
||||
"memory": 2084032512,
|
||||
"cpu_type": "6",
|
||||
"cpu_subtype": "142",
|
||||
"cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz",
|
||||
"cpu_physical_cores": 4,
|
||||
"cpu_logical_cores": 4,
|
||||
"hardware_vendor": "",
|
||||
"hardware_model": "",
|
||||
"hardware_version": "",
|
||||
"hardware_serial": "",
|
||||
"computer_name": "2ceca32fe484",
|
||||
"primary_ip": "",
|
||||
"primary_mac": "",
|
||||
"distributed_interval": 10,
|
||||
"config_tls_refresh": 10,
|
||||
"logger_tls_period": 8,
|
||||
"additional": {},
|
||||
"enroll_secret_name": "default",
|
||||
"status": "offline",
|
||||
"display_text": "2ceca32fe484"
|
||||
},
|
||||
{
|
||||
"created_at": "2020-11-05T05:09:44Z",
|
||||
"updated_at": "2020-11-05T06:03:39Z",
|
||||
"id": 2,
|
||||
"detail_updated_at": "2020-11-05T05:09:45Z",
|
||||
"label_updated_at": "2020-11-05T05:14:52Z",
|
||||
"seen_time": "2020-11-05T06:03:40Z",
|
||||
"hostname": "4cc885c20110",
|
||||
"uuid": "392547dc-0000-0000-a87a-d701ff75bc65",
|
||||
"platform": "centos",
|
||||
"osquery_version": "2.7.0",
|
||||
"os_version": "CentOS 6.8.0",
|
||||
"build": "",
|
||||
"platform_like": "rhel",
|
||||
"code_name": "",
|
||||
"uptime": 8305000000000,
|
||||
"memory": 2084032512,
|
||||
"cpu_type": "6",
|
||||
"cpu_subtype": "142",
|
||||
"cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz",
|
||||
"cpu_physical_cores": 4,
|
||||
"cpu_logical_cores": 4,
|
||||
"hardware_vendor": "",
|
||||
"hardware_model": "",
|
||||
"hardware_version": "",
|
||||
"hardware_serial": "",
|
||||
"computer_name": "4cc885c20110",
|
||||
"primary_ip": "",
|
||||
"primary_mac": "",
|
||||
"distributed_interval": 10,
|
||||
"config_tls_refresh": 10,
|
||||
"logger_tls_period": 8,
|
||||
"additional": {},
|
||||
"enroll_secret_name": "default",
|
||||
"status": "offline",
|
||||
"display_text": "4cc885c20110"
|
||||
},
|
||||
]
|
||||
}
|
||||
```
|
||||
*******
|
||||
|
|
|
|||
Loading…
Reference in a new issue