Skip to main content
Connect to Fleet Device Management using an API token
This guide walks you through creating a Fleet API token and connecting it for device management automation.

​
Prerequisites

Before you begin, ensure you have:
  • Fleet Device Management instance (cloud or self-hosted)
  • Fleet admin or maintainer access
  • Your Fleet server URL

​
Setup guide

​
Create Fleet API token

1

Access Fleet admin console

Navigate to your Fleet instance and sign in with an admin or maintainer account
2

Navigate to API settings

  1. Click on your profile icon in the top right
  2. Select Settings
  3. Go to the API tab
3

Create new API token

  1. Click Create API token
  2. Enter a descriptive name (e.g., “Device Management Integration”)
  3. Select the appropriate role:
    • Maintainer: Recommended for full device management capabilities
    • Observer: For read-only access to device information
  4. Click Create
4

Copy the API token

Copy the API token immediately. Fleet only displays it once and you won’t be able to retrieve it later.
Store the token securely - you’ll need it to configure the integration.

​
Add integration

1

Navigate to integrations

  1. Go to Settings > Integrations
  2. Find Fleet in the Device Management section
2

Select Fleet

Click Connect on the Fleet Device Management integration card
3

Configure Fleet credentials

Provide the following information:
​
serverUrl
string
required
Your Fleet server URL (e.g., https://fleet.company.com or https://your-org.fleetdm.com)
For Fleet Cloud customers, use your Fleet Cloud URL. For self-hosted instances, use your custom domain.
​
apiToken
string
required
The API token you created in the previous step
4

Complete setup

Click Connect to complete the integration. This will:
  1. Validate the API token
  2. Test connectivity to your Fleet server
  3. Verify API permissions

​
Troubleshooting

Cause: API token is invalid, expired, or revokedSolution:
  • Verify the token was copied correctly (no extra spaces or characters)
  • Check if the token still exists in Fleet Settings > API
  • Create a new API token if the current one is invalid
  • Update the token in integration settings
Cause: Cannot reach Fleet server URLSolution:
  • Verify the server URL is correct and accessible
  • Check if your Fleet instance is behind a firewall
  • Ensure the URL includes the protocol (https://)
  • For self-hosted instances, verify DNS resolution
Cause: API token doesn’t have required permissionsSolution:
  • Verify the API token has Maintainer or Observer role
  • For workflow actions that modify devices, Maintainer role is required
  • Recreate the token with appropriate permissions
Cause: Cannot match user to a Fleet deviceSolution:
  • Verify the device is enrolled in Fleet
  • Check device hostname matches user email prefix (e.g., john.doe for john.doe@company.com)
  • Update device display name to include user email
  • Ensure the device is online and reporting to Fleet
Cause: Diagnostic query took too long to executeSolution:
  • Verify the device is online and connected to Fleet
  • Simplify the osquery SQL statement
  • Check device performance and resource availability
  • Increase timeout in workflow configuration if needed

​
Features

Once connected, you can use Fleet actions in workflows:
https://mintcdn.com/ravenna/sHkIxR1kZRcsw3Gd/icons/fleet.svg?fit=max&auto=format&n=sHkIxR1kZRcsw3Gd&q=85&s=25f1145c3f95fd4fc8454d833ccf29a5

Fleet Device Management Actions

Get device info, check device health, query software inventory, and run diagnostic queries using osquery