> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fleet

> Connect Fleet (FleetDM) device management to Serval to look up, lock, wipe, and audit company devices through workflows and the full Fleet API.

## About Fleet

Fleet (FleetDM) is an open-source device management (MDM) and osquery platform. Serval connects to either Fleet cloud or a self-hosted Fleet server using an API token, then lets your team run device workflows - look up a user's laptop, lock or wipe a lost device, recover a disk encryption key, audit installed software - and reach the rest of the Fleet API on demand. The integration appears as **Fleet** in the Serval app.

**Authentication:** API token (Bearer). Serval stores your Fleet domain and API token and attaches the token to every request on its own servers - the token never reaches workflow code.

**Data sync:** On-demand only. There is no background sync and no data ingestion; Serval calls your Fleet instance at the moment a workflow or API action runs.

## What the Fleet integration enables

| Capability                              | Description                                                                                                                                                                                                                                                                            |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Full Fleet REST API access              | A typed API action covering 156 Fleet API endpoints (203 operations): hosts, queries, policies, scripts, software, teams, users, MDM commands (lock, unlock, wipe), configuration profiles, vulnerabilities, labels, and activities. Works with Fleet cloud and self-hosted instances. |
| Device Management bundle                | An installable bundle of six of the workflows below: "Lock, wipe, and retrieve information about Fleet-managed devices." It includes the lock, wipe, disk encryption key, host software, active workstation, and computers-for-user workflows.                                         |
| List Fleet DM Computers for User        | Retrieves all hosts associated with a user's email address, paging through the full list automatically. No approval required by default.                                                                                                                                               |
| Get User Active Fleet Workstation       | Returns the most recently active workstation (non-mobile device) for a user. No approval required by default.                                                                                                                                                                          |
| Run Fleet DM Query on User Workstations | Runs a Fleet query (by query ID) live against a user's workstation hosts - mobile devices are excluded - and returns per-host results plus an AI-generated summary of the data. No approval required by default.                                                                       |
| Lock Fleet DM Host                      | Finds the user's most recently seen workstation and sends a remote lock command - useful for lost or stolen laptops. Also requests the unlock PIN, which Fleet provides for macOS hosts. Requires installer approval by default.                                                       |
| Wipe Fleet DM Host                      | Finds the user's most recently seen workstation and sends a remote wipe command; the device is wiped once it comes online. Requires installer approval by default.                                                                                                                     |
| Get Fleet DM Host Disk Encryption Key   | Retrieves the disk encryption recovery key (FileVault or BitLocker) for a user's most recently active workstation. Requires installer approval by default.                                                                                                                             |
| Get Fleet DM Host Software              | Lists all installed software on a user's most recently active workstation, for troubleshooting or auditing. No approval required by default.                                                                                                                                           |
| List Fleet DM Policies                  | Lists all global policies in Fleet, including pass/fail host counts, for compliance auditing. No approval required by default.                                                                                                                                                         |

The endpoints available through Serval mirror the [Fleet REST API](https://fleetdm.com/docs/rest-api/rest-api) - see Fleet's documentation for what each endpoint does.

## Get your credentials

You need two things: your Fleet domain and a Fleet API token. The token belongs to a Fleet user account and inherits that account's role, so create it from an account with enough privileges (Admin or Maintainer for some operations). See [Fleet's REST API documentation](https://fleetdm.com/docs/rest-api/rest-api) for details.

<Steps>
  <Step title="Log in to your Fleet instance">
    Sign in to Fleet cloud (for example, yourcompany.cloud.fleetdm.com) or your self-hosted Fleet server.
  </Step>

  <Step title="Open your account profile">
    Go to **My account**, then choose **Get API token**.
  </Step>

  <Step title="Copy and save the token immediately">
    You will not be able to see it again after closing the dialog.
  </Step>

  <Step title="Note your Fleet domain">
    This is the address you use to reach Fleet, without any https\:// prefix - for example, yourcompany.cloud.fleetdm.com or fleet.yourcompany.com.
  </Step>
</Steps>

<Note>
  Tokens taken from a regular Fleet UI user are session-scoped and can expire when that user logs out. For long-lived automation, Fleet recommends a dedicated API-only user. A token can also be obtained programmatically via Fleet's login API.
</Note>

<Warning>
  The token inherits the role of the Fleet user it belongs to. Listing users and policies, sending lock and wipe commands, and retrieving disk encryption keys require elevated roles (Admin or Maintainer) in Fleet.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the Fleet integration">
    In Serval, find **Fleet** in the integrations list and choose to connect it.
  </Step>

  <Step title="Enter your API Domain (required)">
    Enter the bare domain only - no https\:// prefix and no trailing path. The form shows the example "yourcompany.cloud.fleetdm.com" and the help text "Your Fleet domain (without https\:// or trailing path). For example: yourcompany.cloud.fleetdm.com or fleet.yourcompany.com". Anything that is not a plain domain is rejected with "Enter a valid Fleet domain (e.g., yourcompany.cloud.fleetdm.com or fleet.yourcompany.com)". Leaving it empty shows "This field is required".
  </Step>

  <Step title="Enter your API Token (required)">
    Paste the token into this password field. The help text reads "Your Fleet API token. You can get this from your user profile in Fleet UI or via the login API." Leaving it empty shows "This field is required".
  </Step>

  <Step title="Save the connection">
    Serval immediately verifies the connection by asking Fleet who the token belongs to.
  </Step>
</Steps>

<Tip>
  When you edit an existing connection, the form opens pre-filled: the API Domain shows the saved domain, and the API Token appears masked except for its last 4 characters, with a **Replace** button. Leave the token untouched to keep the saved value - only click **Replace** and paste a new token when you want to rotate it. On the Serval side, a blank domain keeps the existing domain and a blank token keeps the existing token.
</Tip>

## Verifying the connection

The Fleet connection runs five health checks:

* **Get Current User** - confirms Serval can authenticate and identifies the token's user and role.
  Success: "Successfully authenticated as \[name or email] (\[role])"
  Failure: "Unable to authenticate with FleetDM. Please check your API token and domain."
* **List Hosts** - confirms device listing works and captures a few sample devices.
  Success: "Successfully listed hosts from FleetDM (\[number] returned)"
  Failure: "Unable to list hosts from FleetDM. Please check your permissions."
* **List Users** - confirms user listing works and captures a few sample users.
  Success: "Successfully listed users from FleetDM (\[number] returned)"
  Failure: "Unable to list users from FleetDM. Please check your permissions."
* **List Policies** - confirms global policy listing works and captures a few sample policies.
  Success: "Successfully listed policies from FleetDM (\[number] returned)"
  Failure: "Unable to list policies from FleetDM. Please check your permissions."
* **List Queries** - confirms saved-query listing works and captures a few sample queries.
  Success: "Successfully listed queries from FleetDM (\[number] returned)"
  Failure: "Unable to list queries from FleetDM. Please check your permissions."

<Tip>
  If **Get Current User** passes but **List Users** or **List Policies** fails, your token is valid but the Fleet account behind it does not have a high enough role. Switch to a token from an Admin or Maintainer account - the same applies if lock, wipe, or encryption key workflows fail later.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Domain is rejected when connecting">
    The API Domain must be a bare domain - no https\:// prefix and no trailing path. Anything else is rejected with "Enter a valid Fleet domain (e.g., yourcompany.cloud.fleetdm.com or fleet.yourcompany.com)". Both Fleet cloud domains and self-hosted domains are accepted.
  </Accordion>

  <Accordion title="Some checks or workflows fail with permission errors">
    The API token inherits the role of the Fleet user it belongs to. Listing users and policies, lock and wipe commands, and disk encryption key retrieval need an Admin or Maintainer account in Fleet. Tokens from a regular UI user are also session-scoped and can expire when that user logs out - use a dedicated API-only user for long-lived automation.
  </Accordion>

  <Accordion title="Lock, wipe, and encryption key workflows ask for approval">
    Lock Fleet DM Host, Wipe Fleet DM Host, and Get Fleet DM Host Disk Encryption Key require approval from the workflow installer by default. The read-only workflows run without approval. Approval settings can be adjusted when installing the bundle.
  </Accordion>

  <Accordion title="Phones and tablets never appear in workstation workflows">
    Workflows that target "workstations" (lock, wipe, active workstation lookup, query runs) deliberately exclude mobile devices: any host whose platform is iOS, iPadOS, or Android is filtered out, as is any host with no platform recorded. Devices on every other platform (macOS, Windows, Linux) are treated as workstations.
  </Accordion>

  <Accordion title="Cannot find the integration by name">
    The integration displays as **Fleet** in the Serval app, but its internal identifier is "fleetdm". If a search for one name comes up empty, try the other.
  </Accordion>

  <Accordion title="Editing the connection changed something you did not touch">
    It should not - when you edit, the saved domain is pre-filled, an untouched masked token keeps the stored token exactly as it was, and a blank value for either field keeps the existing value. Change only the field you mean to change. If health checks fail after an edit, re-enter the value you changed and save again.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Fleet integration.