Skip to main content
Connect to Fleet Device Management using an API token
This guide walks you through creating a dedicated integration user and API token 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 API-only user and token

Ravenna requires an API-only user token because these tokens don’t expire, making them ideal for long-running integrations. API-only users must be created using the fleetctl CLI tool.
Regular user tokens expire and will cause the integration to stop working. You must use an API-only user token.
Follow Fleet’s documentation to create an API-only user:

Create an API-only user

Learn how to use the fleetctl CLI to create an API-only user and retrieve their API token.
When creating the API-only user, we recommend using the Maintainer role to enable all Ravenna workflow actions. If you only need read-only access, you can use the Observer role instead.

​
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: The API token belongs to a regular user account instead of an API-only userSolution: Create an API-only user using the fleetctl CLI tool and use their token instead. See Fleet’s documentation for instructions.API-only tokens are non-expiring and required for integrations. Regular user tokens expire and will cause the integration to stop working.
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 [email protected])
  • 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