mirror of https://github.com/fleetdm/fleet synced 2026-04-21 13:37:30 +00:00

Fix wrong examples for certificates SN (#43317 )

Documentation is wrong, we use `,` instead of `/`.

---------

Co-authored-by: Rachael Shaw <r@rachael.wtf>

2026-04-14 11:45:50 -05:00

541 KiB

Raw Blame History

REST API

Authentication
Activities
Fleet configuration
File carving
Hosts
Labels
OS Settings
Setup Experience
Commands
Integrations
Policies
Reports
Schedule (deprecated)
Scripts
Sessions
Software
Targets
Fleets
Translator
Users
Custom variables
API errors

Use the Fleet APIs to automate Fleet.

This page includes a list of available resources and their API routes.

Unless otherwise specified, endpoints that accept a request body limit its size to the configured FLEET_SERVER_DEFAULT_MAX_REQUEST_BODY_SIZE (default 1MiB).

Retrieve your API token

All API requests to the Fleet server require API token authentication unless noted in the documentation. API tokens are tied to your Fleet user account.

To get an API token, retrieve it from "My account" > "Get API token" in the Fleet UI (/profile). Or, you can send a request to the login API endpoint to get your token.

Then, use that API token to authenticate all subsequent API requests by sending it in the "Authorization" request header, prefixed with "Bearer ":

Authorization: Bearer <your token>

For SSO and MFA users, email/password login is disabled. The API token can instead be retrieved from the "My account" page in the UI (/profile). On this page, choose "Get API token".

Log in

Authenticates the user with the specified credentials. Use the token returned from this endpoint to authenticate further API requests.

POST /api/v1/fleet/login

Logging in via the API is not supported for SSO and MFA users. The API token can instead be retrieved from the "My account" page in the UI (/profile). On this page, choose "Get API token".

Parameters

Name	Type	In	Description
email	string	body	Required. The user's email.
password	string	body	Required. The user's plain text password.

Example

POST /api/v1/fleet/login

Request body

{
  "email": "janedoe@example.com",
  "password": "VArCjNW7CfsxGp67"
}

Default response

Status: 200

{
  "user": {
    "created_at": "2020-11-13T22:57:12Z",
    "updated_at": "2020-11-13T22:57:12Z",
    "id": 1,
    "name": "Jane Doe",
    "email": "janedoe@example.com",
    "enabled": true,
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "mfa_enabled": false,
    "global_role": "admin",
    "teams": [],
    "fleets": []
  },
  "token": "{your token}"
}

Authentication failed

Status: 401 Unauthorized

{
  "message": "Authentication failed",
  "errors": [
    {
      "name": "base",
      "reason": "Authentication failed"
    }
  ],
  "uuid": "1272014b-902b-4b36-bcdb-75fde5eac1fc"
}

MFA Required

Status: 202 Accepted

{
  "message": "We sent an email to you. Please click the magic link in the email to sign in.",
}

Too many requests / Rate limiting

Status: 429 Too Many Requests Header: retry-after: N

This response includes a header retry-after that indicates how many more seconds you are blocked before you can try again.

{
  "message": "limit exceeded, retry after: Ns",
  "errors": [
    {
      "name": "base",
      "reason": "limit exceeded, retry after: Ns"
    }
  ]
}

Log out

Logs out the authenticated user.

POST /api/v1/fleet/logout

Example

POST /api/v1/fleet/logout

Default response

Status: 200

Forgot password

Sends a password reset email to the specified email. Requires that SMTP or SES is configured for your Fleet server.

POST /api/v1/fleet/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/fleet/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"
    }
  ]
}

Update password

POST /api/v1/fleet/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/fleet/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"
    }
  ]
}

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

Retrieves the user data for the authenticated user.

GET /api/v1/fleet/me

Example

GET /api/v1/fleet/me

Default response

Status: 200

{
  "user": {
    "created_at": "2020-11-13T22:57:12Z",
    "updated_at": "2020-11-16T23:49:41Z",
    "id": 1,
    "name": "Jane Doe",
    "email": "janedoe@example.com",
    "global_role": "admin",
    "enabled": true,
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "fleets": [],
    "fleets": []
  },
  "available_teams" : [
    {
      "id": 1,
      "name": "Workstations",
      "description": "Employee workstations"
    }
  ],
    "available_fleets" : [
    {
      "id": 1,
      "name": "Workstations",
      "description": "Employee workstations"
    }
  ]
}

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/fleet/perform_required_password_reset

Example

POST /api/v1/fleet/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,
    "name": "Jane Doe",
    "email": "janedoe@example.com",
    "enabled": true,
    "force_password_reset": false,
    "gravatar_url": "",
    "sso_enabled": false,
    "global_role": "admin",
    "teams": [],
    "fleets": []
  }
}

SSO config

Gets the current SSO configuration.

GET /api/v1/fleet/sso

Example

GET /api/v1/fleet/sso

Default response

Status: 200

{
  "settings": {
    "idp_name": "IDP Vendor 1",
    "idp_image_url": "",
    "sso_enabled": false
  }
}

Initiate SSO

POST /api/v1/fleet/sso

A successful response contains an HTTP cookie __Host-FLEETSSOSESSIONID that needs to be sent on the POST /api/v1/fleet/sso/callback request (this HTTP cookie is used to identify the SSO login session).

Parameters

Name	Type	In	Description
relay_url	string	body	Required. The relative url to be navigated to after successful sign in.

Example

POST /api/v1/fleet/sso

Request body

{
  "relay_url": "/hosts/manage"
}

Default response

Status: 200

Example response cookie in the HTTP Set-Cookie header:

Set-Cookie: __Host-FLEETSSOSESSIONID=slI727JZ+j0FvyBRLyD/gri1rxtwpaZT; Path=/; Max-Age=300; HttpOnly; Secure

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"
    }
  ]
}

SSO callback

This is the callback endpoint that the identity provider will use to send security assertions to Fleet. This is where Fleet receives and processes the response from the identify provider.

POST /api/v1/fleet/sso/callback

The __Host-FLEETSSOSESSIONID HTTP cookie must be set for non-IdP initiated SSO login requests. The value for this cookie is returned in the POST /api/v1/fleet/sso request. For IdP-initiated SSO logins the cookie doesn't need to be set.

Parameters

Name	Type	In	Description
SAMLResponse	string	body	Required. The SAML response from the identity provider.
__Host-FLEETSSOSESSIONID	string	cookie	HTTP Cookie returned in the `POST /api/v1/fleet/sso` request. This is not set/required for IdP initiated SSO logins

Example

POST /api/v1/fleet/sso/callback

Request body

{
  "SAMLResponse": "<SAML response from IdP>"
}

Example session cookie set in the Cookie request header:

Cookie: __Host-FLEETSSOSESSIONID=slI727JZ+j0FvyBRLyD/gri1rxtwpaZT

Default response

Status: 200

Activities

List activities

Returns a list of the activities that have been performed in Fleet. For a comprehensive list of activity types and detailed information, please see the audit logs page.

GET /api/v1/fleet/activities

Parameters

Name	Type	In	Description
page	integer	query	Page number of the results to fetch.
per_page	integer	query	Results per page. Maximum is 10,000 records. If no pagination parameters are specified, defaults to 10,000.
order_key	string	query	What to order results by. Can be any column in the `activities` 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"`.
after	string	query	The value to get results after. This needs `order_key` defined, as that's the column that would be used.
query	string	query	Search query keywords. Searchable fields include `actor_full_name` and `actor_email`.
activity_type	string	query	Indicates the activity `type` to filter by. See available activity types in the Audit logs docs.
start_created_at	string	query	Filters to include only activities that happened after this date. If not specified, set to the earliest possible date.
end_created_at	string	query	Filters to include only activities that happened before this date. If not specified, set to now.

Example

GET /api/v1/fleet/activities?page=0&per_page=10&order_key=created_at&order_direction=desc

Default response

{
  "activities": [
    {
      "created_at": "2023-07-27T14:35:08Z",
      "id": 25,
      "actor_full_name": "Anna Chao",
      "actor_id": 3,
      "actor_gravatar": "",
      "actor_email": "",
      "type": "installed_software",
      "fleet_initiated": false,
      "details": {
        "status": "installed",
        "host_id": 1272,
        "host_display_name": "MacBook Pro",
        "policy_id": null,
        "policy_name": null,
        "install_uuid": "23c18ea1-8cd7-4af4-a1d8-f2666993a66b",
        "self_service": false,
        "software_title": "zoom.us.app",
        "software_package": "ZoomInstallerIT.pkg",
      }
    },
    {
      "created_at": "2021-07-29T14:40:27Z",
      "id": 21,
      "actor_full_name": "name",
      "actor_id": 1,
      "actor_gravatar": "",
      "actor_email": "name@example.com",
      "type": "created_team",
      "type": "created_fleet",
      "fleet_initiated": false,
      "details": {
        "team_id": 2,
        "fleet_id": 2,
        "team_name": "Apples",
        "fleet_name": "Apples"
      }
    },
    {
      "created_at": "2023-07-27T14:35:08Z",
      "id": 25,
      "type": "installed_software",
      "fleet_initiated": true,
      "details": {
        "status": "installed",
        "host_id": 1272,
        "host_display_name": "MacBook Pro",
        "policy_id": 24,
        "policy_name": "[Install software] Zoom",
        "install_uuid": "077970ab-0ed6-4573-9cdc-ca9ef9015283",
        "self_service": false,
        "software_title": "zoom.us.app",
        "software_package": "ZoomInstallerIT.pkg",
      }
    }
  ],
  "meta": {
    "has_next_results": false,
    "has_previous_results": false
  }
}

Certificates

Connect certificate authority (CA)
Add certificate template
Update certificate authority (CA)
List certificate authorities (CAs)
Get certificate authority (CA)
List certificate templates
Get certificate template
Delete certificate authority (CA)
Delete certificate template
Request certificate

Connect certificate authority (CA)

Connect Fleet to a certificate authority (CA). Fleet currently supports DigiCert, Microsoft NDES, Hydrant, Smallstep, and any custom SCEP or EST CA.

POST /api/v1/fleet/certificate_authorities

Only one of the objects is allowed in a single request.