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

# Setup

> Connect Fleet to Ravenna by creating an API-only user with fleetctl and providing the API token and server URL during integration setup.

<Info>Connect to Fleet Device Management using an API token</Info>

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

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

<Warning>
  Regular user tokens expire and will cause the integration to stop working. You must use an API-only user token.
</Warning>

Follow Fleet's documentation to create an API-only user:

<Card title="Create an API-only user" icon="arrow-up-right-from-square" href="https://fleetdm.com/guides/fleetctl#using-fleetctl-with-an-api-only-user">
  Learn how to use the `fleetctl` CLI to create an API-only user and retrieve their API token.
</Card>

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

### Add integration

<Steps>
  <Step title="Navigate to integrations">
    1. Go to **Settings > Integrations**
    2. Find **Fleet** in the Device Management section
  </Step>

  <Step title="Select Fleet">
    Click **Connect** on the Fleet Device Management integration card
  </Step>

  <Step title="Configure Fleet credentials">
    Provide the following information:

    <ParamField path="serverUrl" type="string" required>
      Your Fleet server URL (e.g., `https://fleet.company.com` or `https://your-org.fleetdm.com`)

      <Note>
        For Fleet Cloud customers, use your Fleet Cloud URL. For self-hosted instances, use your custom domain.
      </Note>
    </ParamField>

    <ParamField path="apiToken" type="string" required>
      The API token you created in the previous step
    </ParamField>
  </Step>

  <Step title="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
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="API-only user required error" icon="user-x">
    **Cause**: The API token belongs to a regular user account instead of an API-only user

    **Solution**: Create an API-only user using the `fleetctl` CLI tool and use their token instead. See [Fleet's documentation](https://fleetdm.com/guides/fleetctl#using-fleetctl-with-an-api-only-user) for instructions.

    API-only tokens are non-expiring and required for integrations. Regular user tokens expire and will cause the integration to stop working.
  </Accordion>

  <Accordion title="Invalid API token error" icon="circle-x">
    **Cause**: API token is invalid, expired, or revoked

    **Solution**:

    * 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
  </Accordion>

  <Accordion title="Connection timeout error" icon="clock">
    **Cause**: Cannot reach Fleet server URL

    **Solution**:

    * 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
  </Accordion>

  <Accordion title="Insufficient permissions error" icon="shield-x">
    **Cause**: API token doesn't have required permissions

    **Solution**:

    * 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
  </Accordion>

  <Accordion title="Host not found for user" icon="user-search">
    **Cause**: Cannot match user to a Fleet device

    **Solution**:

    * 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
  </Accordion>

  <Accordion title="Query execution timeout" icon="hourglass">
    **Cause**: Diagnostic query took too long to execute

    **Solution**:

    * 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
  </Accordion>
</AccordionGroup>