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

# Kolide

> Connect Serval to Kolide so workflows can inspect device trust posture, manage registrations, and call the Kolide device-security API.

## About Kolide

Kolide is a device trust platform that verifies endpoint security posture before users authenticate to company resources. The Serval Kolide integration connects to `api.kolide.com` with a Kolide API token so workflows can list devices and people, review open issues, deprovision devices, and approve registration or exemption requests. The integration is marked **Beta** in Serval's connect UI.

**Authentication:** API token (Bearer). Tokens start with `k2sk_`. Serval stores the token encrypted and sends it only to `api.kolide.com`.

**Data sync:** On demand only. There is no background sync or asset ingestion.

## What the Kolide integration enables

| Capability          | Description                                                                                                                                                                           |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Device Trust bundle | Prebuilt workflows: list a user's devices by email, list their open issues, get device posture for a device ID, deprovision a device, and approve exemption or registration requests. |
| Kolide API request  | Typed access to the Kolide v1 API from custom workflows — devices, people, issues, checks, and admin operations your token can perform.                                               |

Install the **Device Trust** bundle from Workflows → Installable, or build custom workflows with the Kolide API request action.

## Get your credentials

You need a Kolide API token created by a **Full Access** administrator.

<Steps>
  <Step title="Sign in to Kolide as a Full Access admin">
    API key management requires Full Access admin privileges in Kolide.
  </Step>

  <Step title="Open Settings → Developers → API Keys">
    Navigate to the API Keys section in Kolide settings.
  </Step>

  <Step title="Create a new API key">
    Generate a token and copy it immediately. Kolide tokens start with `k2sk_`.
  </Step>

  <Step title="Paste the token into Serval">
    Use the **API Token** password field in Serval's Kolide connect form.
  </Step>
</Steps>

<Warning>
  Treat Kolide API tokens like production credentials. A Full Access token can deprovision devices and approve security exceptions — scope access to the service account that owns the Serval connection.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the Kolide connect form">
    In Serval, add the Kolide integration. It is labeled **Beta**.
  </Step>

  <Step title="API Token (required)">
    Paste your Kolide API token (`k2sk_…`) into the password field.
  </Step>

  <Step title="Save and verify">
    Submit the form. Serval runs four health checks (below).
  </Step>
</Steps>

<Note>
  When editing an existing connection, leave the token field as its obfuscated placeholder to keep the stored token, or paste a new token to rotate.
</Note>

## Verifying the connection

Four health checks run after you connect:

1. **Test Connection** — calls `GET /whoami`. Success: `Connected to Kolide organization "…"`. Failure: `Unable to authenticate with Kolide. Please check your API token.`
2. **List Devices** — fetches up to 10 devices. Failure usually indicates insufficient token permissions for device reads.
3. **List People** — fetches up to 10 people records.
4. **List Issues** — fetches up to 10 open issues.

<Tip>
  If authentication succeeds but list checks fail, the token is valid but may lack read scopes for that resource type. Regenerate the token with Full Access or adjust Kolide API key permissions.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Full Access admin is required to create tokens">
    Standard Kolide roles without Developers access cannot reach the API Keys page.
  </Accordion>

  <Accordion title="Deprovision and approval workflows require installer approval by default">
    Mutating workflows in the Device Trust bundle ship with installer approval. Adjust approval procedures after install if your team wants different governance.
  </Accordion>

  <Accordion title="User lookups use email">
    Device Trust workflows resolve Kolide users by email address. Ensure requesters' corporate emails match their Kolide person records.
  </Accordion>

  <Accordion title="List endpoints paginate">
    Kolide returns paginated result sets. Prebuilt workflows page automatically; custom workflows should request additional pages until a short page is returned.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Kolide integration.