Skip to main content

​
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

The endpoints available through Serval mirror the Fleet 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 for details.
1

Log in to your Fleet instance

Sign in to Fleet cloud (for example, yourcompany.cloud.fleetdm.com) or your self-hosted Fleet server.
2

Open your account profile

Go to My account, then choose Get API token.
3

Copy and save the token immediately

You will not be able to see it again after closing the dialog.
4

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.
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.
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.

​
Connect in Serval

1

Open the Fleet integration

In Serval, find Fleet in the integrations list and choose to connect it.
2

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”.
3

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”.
4

Save the connection

Serval immediately verifies the connection by asking Fleet who the token belongs to.
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.

​
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.”
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.

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.
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.
Need help? Contact support@serval.com for assistance with your Fleet integration.