# Kolide

SureCloud connects to Kolide to retrieve device inventory, compliance check results, and security policy status from Kolide's osquery-based device compliance platform. This allows SureCloud to confirm that enrolled devices meet your organisation's security baseline — verifying disk encryption, screen lock configuration, software inventory, and other endpoint controls — and to identify devices that are out of compliance.

## Authentication and setup

Kolide authenticates API requests using an API token. SureCloud uses a read-only API token generated within your Kolide account.

{% stepper %}
{% step %}
**Generate an API token in Kolide**

Log in to your Kolide console at [k2.kolide.com](https://k2.kolide.com/). Navigate to **Settings → API** and click **Create New Token**. Give it a descriptive name such as `SureCloud CCM`. Copy the token — it is only displayed once.
{% endstep %}

{% step %}
**Enter the token in SureCloud**

Navigate to **SureCloud → Integrations → Kolide → Connect**. Paste the API token into the **API Token** field and click **Save**.
{% endstep %}

{% step %}
**Test the connection**

Click **Test Connection**. SureCloud will call `GET /v0/devices` to confirm connectivity and token validity. A green status confirms the integration is active.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the API token securely after copying it. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **Kolide → Settings → API** and update it in **SureCloud → Integrations → Kolide → Edit Connection**.
{% endhint %}

## Endpoints

| API Call                | Use Case                                                                         |
| ----------------------- | -------------------------------------------------------------------------------- |
| `GET /v0/devices`       | Enumerate all enrolled devices including OS, owner, and last check-in time       |
| `GET /v0/devices/{id}`  | Retrieve individual device detail including compliance status and failing checks |
| `GET /v0/checks`        | List all security checks configured in Kolide and their pass/fail thresholds     |
| `GET /v0/check_results` | Retrieve per-device check results to evidence compliance status                  |
| `GET /v0/issues`        | Retrieve open compliance issues and their associated devices and severity        |
| `GET /v0/persons`       | Enumerate Kolide users (device owners) to map devices to employee identities     |

## Pagination

`GET /v0/devices` and `GET /v0/issues` support cursor-based pagination. SureCloud uses the `next_cursor` value from each response as the `cursor` parameter in the next request, continuing until no `next_cursor` is returned.

```json
GET /v0/devices?per_page=100&cursor=<value_from_previous_response>
```

`GET /v0/checks` and `GET /v0/persons` typically return complete result sets in a single response for most account sizes. `GET /v0/check_results` uses the same cursor pattern as devices.

## Required permissions

Kolide API tokens are account-scoped and read-only. The token SureCloud uses must have access to the following resource types:

* Devices (read)
* Checks and check results (read)
* Issues (read)
* Persons (read)

No write or administrative permissions are required.

## Polling frequency

| Data Type                              | Interval       |
| -------------------------------------- | -------------- |
| Device inventory and compliance status | Every 24 hours |
| Security check results                 | Every 24 hours |
| Open compliance issues                 | Every 12 hours |
| Device owner (persons) mapping         | Every 24 hours |

## Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized</summary>

The API token is invalid or has been revoked. Navigate to **Kolide → Settings → API**, confirm the token exists, and generate a new one if needed. Update it in **SureCloud → Integrations → Kolide → Edit Connection**.

</details>

<details>

<summary>Device count in SureCloud is lower than the enrolled device count in Kolide</summary>

Kolide may mark some devices as inactive or unenrolled if the Kolide agent has not checked in recently. SureCloud collects all enrolled devices regardless of last check-in time, but devices in a permanently offline state may be excluded from compliance results. Review device status directly in the Kolide console to identify devices that have stopped reporting.

</details>

<details>

<summary>Check results are missing for some devices</summary>

Check results are only generated for devices that have run the relevant osquery checks. If a device enrolled recently or a check was newly added to Kolide, results may not yet be available. Kolide pushes check execution to devices asynchronously — results will appear in SureCloud after the next polling cycle once the device has completed the check.

</details>

<details>

<summary>Issues count in SureCloud does not match Kolide's dashboard</summary>

Kolide's dashboard may display issues across multiple severity levels including informational. SureCloud collects issues at all severity levels but displays them filtered by the thresholds configured for your SureCloud controls. If you see a discrepancy, check the severity filter settings in SureCloud for the Kolide integration.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/kolide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.