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 integration user and API token

API tokens in Fleet are always associated with user accounts. Create a dedicated integration user to generate the API token for Ravenna.
1

Create integration user

  1. Sign in to Fleet with an admin account
  2. Navigate to Settings > Users
  3. Click Create user
  4. Enter the following details:
    • Name: Ravenna Integration
    • Email: Use a dedicated email address (e.g., ravenna-integration@company.com)
    • Role: Select Maintainer for full device management capabilities
  5. Click Create
The Maintainer role is recommended to enable all Ravenna workflow actions. If you only need read-only access, you can use the Observer role instead.
2

Get API token

  1. Sign in to Fleet as the integration user you just created
  2. Navigate to /account or click on your profile icon and select My account
  3. Click Get API token
  4. Copy the API token
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