> ## 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.

# Kandji

> Kandji is Apple device management (MDM) for your Mac fleet - Serval connects to it to run device workflows, automate compliance checks, and sync your Macs into Serval's asset inventory.

## About Kandji

Kandji is a cloud-native Apple device management (MDM) and security platform for deploying, configuring, and protecting Macs and other Apple devices at scale. The Serval Kandji integration connects to your Kandji tenant using an API token plus your tenant's API domain, and all traffic flows securely through Serval. Once connected, Serval gets typed access to the full Kandji v1 API (roughly 80 endpoints), plus prebuilt device-inventory and device-compliance workflow bundles and an ingestion workflow that syncs your Mac computers into Serval's asset inventory.

**Authentication:** API token (API Key + API Domain)
**Data sync:** On-demand through workflows, plus an installable "Ingest Kandji Computers" workflow that performs a full sync of your Mac devices into Serval's asset inventory on each run.

## What the Kandji integration enables

| Capability                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Kandji API requests         | The "Kandji API request" action makes typed calls across the Kandji v1 API: devices and device details, device secrets (FileVault key, bypass code, recovery password, unlock PIN), 17 device actions (restart, shut down, lock, erase, lost mode, rename, and more), blueprints and library items, Prism reports, tags, users, threat details, Apple ADE integrations, self-service categories, and settings/licensing.    |
| Device Inventory workflows  | Prebuilt bundle: Get Kandji Device Details, Get All Kandji Devices (full inventory, automatically fetched across pages), and Get Kandji Devices for User (looked up by email).                                                                                                                                                                                                                                              |
| Device Compliance workflows | Prebuilt bundle: Find Kandji Devices with Failing Updates, Check Kandji Devices Not Checked In Today, Check Overdue macOS Updates in Kandji, List Kandji Devices with Less Than 100 GB Free Space, and Check Device Uptime and Restart if Needed (restarts a user's device, with a notification to the user, when uptime exceeds 10 days - this one requires installer approval by default; the rest run without approval). |
| Mac asset ingestion         | The "Ingest Kandji Computers" workflow syncs every Mac in Kandji into Serval's asset inventory, enriching each record with detailed per-device information where available.                                                                                                                                                                                                                                                 |
| Connection health checks    | Three built-in checks exercise different parts of the Kandji API, so a token-permission gap shows up as exactly one failing check instead of a vague error.                                                                                                                                                                                                                                                                 |

Anything defined in the [Kandji API](https://api-docs.kandji.io/) can be accessed through Serval.

## Get your credentials

You need two things from Kandji: an **API token** and your tenant's **API domain**. Kandji's official guide is the [Kandji API support article](https://support.kandji.io/kb/kandji-api).

<Note>
  Kandji is rebranding to Iru, so the API reference at api-docs.kandji.io currently redirects to api-docs.iru.com ("Iru Endpoint Management API"). The link works - just expect the Iru brand on the docs site.
</Note>

<Steps>
  <Step title="Sign in to Kandji with the right role">
    Sign in as an Account Owner or Administrator. Roles without Settings access (such as Standard or Help Desk) cannot reach the Access tab unless granted a custom permission set.
  </Step>

  <Step title="Create the API token">
    Go to **Settings**, open the **Access** tab, scroll to the **API token** section, and click **Add API Token**. Name it (for example, "Serval Integration"), optionally add a description, and click **Create**.
  </Step>

  <Step title="Copy the token immediately">
    Copy the token and store it securely, then confirm the "I have copied the token..." checkbox and click **Next**.

    <Warning>
      Kandji never displays the cleartext token again after this screen. If you lose it, you'll have to create a new token.
    </Warning>
  </Step>

  <Step title="Grant the token's API permissions">
    In the **Manage API Permissions** dialog, click **Configure** and enable a permission for each capability Serval will use. At minimum (for the health checks and asset sync): **Tag list**, **Device list**, **Device details**, and **Blueprint list**. Add **Device ID** and device-action permissions such as **Restart device** if you plan to install the inventory or compliance workflow bundles. Click **Save**.

    <Note>
      Kandji permissions are granted per endpoint, and you can edit them later via the token's **View > Permissions** tab. A missing permission causes a "permission denied" error on that one call while everything else works.
    </Note>
  </Step>

  <Step title="Determine your API domain">
    <Tip>
      If your Kandji dashboard is at acme.kandji.io, your API domain is **acme.api.kandji.io**. EU tenants use **acme.api.eu.kandji.io**. The API domain is not the same as your dashboard address.
    </Tip>
  </Step>
</Steps>

## Connect in Serval

<Steps>
  <Step title="Open the Kandji connection form">
    In Serval, open the Kandji integration and start a new connection.
  </Step>

  <Step title="Enter the API Domain (required)">
    Enter your tenant's API domain, for example yourcompany.api.kandji.io (or yourcompany.api.eu.kandji.io for EU tenants). The field validates the format and rejects anything else with: "Must be a valid Kandji API domain (e.g., yourcompany.api.kandji.io or yourcompany.api.eu.kandji.io)"
  </Step>

  <Step title="Enter the API Key (required)">
    Paste the full Kandji API token into the **API Key** password field.
  </Step>

  <Step title="Save the connection">
    Save, then verify the connection using the health checks below.
  </Step>
</Steps>

<Note>
  **When editing an existing connection:** the stored API Key is shown obfuscated, so you must re-paste the full token to update it. Leaving **API Domain** blank on an update keeps the previously saved domain.
</Note>

Serval only ever sends your token to your own Kandji API host - addresses ending in .api.kandji.io or .api.eu.kandji.io. Any other destination receives no credentials.

## Verifying the connection

The integration ships three health checks, each exercising a different part of the Kandji API:

1. **Test Kandji Connection** - verifies authentication with a lightweight call that lists your tags. Success: "Successfully authenticated with Kandji at \[your API domain]". Failure: "Unable to connect to Kandji at \[your API domain]." followed by a specific reason - for example, an expired token adds: "The API token is invalid or expired. Please verify your API token in the Kandji integration settings."
2. **List Kandji Devices** - lists up to 100 devices and counts them. Success: "Successfully listed \[number] devices from Kandji". Failure: "Unable to list devices from Kandji." plus a specific reason.
3. **List Kandji Blueprints** - lists your blueprints and counts them. Success: "Successfully listed \[number] blueprints from Kandji". Failure: "Unable to list blueprints from Kandji." plus a specific reason.

If Kandji itself is having a temporary problem, the device and blueprint checks append: "Kandji returned a server error. This is likely a temporary issue with Kandji's API - please try again later." The connection check words it as: "Kandji returned a server error during authentication. This is likely a temporary issue - please try again later."

<Tip>
  If the connection test passes but the devices or blueprints check fails, your token authenticates fine but is missing one endpoint permission. The failing check tells you exactly which one to add in Kandji: a failing device check means the **Device list** permission is missing; a failing blueprint check means **Blueprint list** is missing.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="One health check or workflow fails with a permissions error while everything else works">
    Kandji API tokens carry a per-endpoint permission list. A token missing one permission returns "permission denied" on that single call - Serval surfaces this as: "The Kandji API token may not have the required permissions. Please check that the necessary privileges are granted." (The connection check words it slightly differently: "The API token is not authorized to access Kandji. Please ensure the token has been granted the necessary permissions in Kandji.") Fix it in Kandji under the token's **View > Permissions** tab. The asset sync additionally needs **Device details**, and the prebuilt workflow bundles need **Device ID** plus device-action permissions such as **Restart device** (for the uptime-restart workflow).
  </Accordion>

  <Accordion title="A check fails saying a resource was not found">
    Missing permissions can also surface as a not-found error: "The requested Kandji resource was not found. This may indicate missing permissions or incorrect API domain configuration." Verify both the token's endpoint permissions in Kandji and the **API Domain** value in Serval before assuming the resource doesn't exist.
  </Accordion>

  <Accordion title="The API Domain is rejected, or nothing connects at all">
    Enter the API subdomain (acme.api.kandji.io), not your dashboard address (acme.kandji.io). EU tenants use acme.api.eu.kandji.io. The form rejects anything else with: "Must be a valid Kandji API domain (e.g., yourcompany.api.kandji.io or yourcompany.api.eu.kandji.io)" - and Serval only attaches your token to requests bound for valid Kandji API hosts, so a wrong domain means no credentials are ever sent.
  </Accordion>

  <Accordion title="Authentication fails with an invalid or expired token">
    The connection check reports: "The API token is invalid or expired. Please verify your API token in the Kandji integration settings." The device and blueprint checks word the same problem as: "The Kandji API token may be invalid or expired. Please verify your API token is correct." Kandji shows the cleartext token only once at creation, and Serval obfuscates the stored key - so to fix this, create or retrieve a valid token in Kandji and re-paste the **full** token when editing the connection. You can leave **API Domain** blank to keep the existing domain.
  </Accordion>

  <Accordion title="iPhones, iPads, and Apple TVs don't appear in Serval's asset inventory">
    The "Ingest Kandji Computers" workflow syncs Mac devices only. Non-Mac Apple devices are not ingested as assets, but they remain fully reachable through the "Kandji API request" action and the inventory and compliance workflows.
  </Accordion>

  <Accordion title="A custom device-listing workflow returns at most 300 devices">
    Kandji returns list results in pages, with a maximum of 300 records per page. Serval's prebuilt workflows (including Get All Kandji Devices and the asset sync) page through automatically; if you build your own workflow, keep requesting pages until one returns fewer records than the limit.
  </Accordion>

  <Accordion title="The Kandji API docs link shows the Iru brand">
    Kandji is rebranding to Iru, and api-docs.kandji.io redirects to api-docs.iru.com. The content is the same Kandji API; the [support article on creating API tokens](https://support.kandji.io/kb/kandji-api) remains live under the Kandji brand.
  </Accordion>
</AccordionGroup>

***

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