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

# Iru

> Iru (formerly Kandji) is a device management (MDM) platform 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 Iru

Iru is a cloud-native device management (MDM) and security platform for deploying, configuring, and protecting Macs and other Apple devices at scale. The Serval Iru integration connects to your Iru 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 Iru 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 Iru Computers" workflow that performs a full sync of your Mac devices into Serval's asset inventory on each run.

## What the Iru integration enables

| Capability                  | Description                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Iru API requests            | The "Iru API request" action makes typed calls across the Iru 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 Iru Device Details, Get All Iru Devices (full inventory, automatically fetched across pages), and Get Iru Devices for User (looked up by email).                                                                                                                                                                                                                                              |
| Device Compliance workflows | Prebuilt bundle: Find Iru Devices with Failing Updates, Check Iru Devices Not Checked In Today, Check Overdue macOS Updates in Iru, List Iru 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 Iru Computers" workflow syncs every Mac in Iru 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 Iru API, so a token-permission gap shows up as exactly one failing check instead of a vague error.                                                                                                                                                                                                                                                           |

Anything defined in the [Iru API](https://api-docs.iru.com/) can be accessed through Serval.

## Get your credentials

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

<Note>
  Tenant hostnames and the support article still use the kandji.io domain.
</Note>

<Steps>
  <Step title="Sign in to Iru 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>
      Iru 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>
      Iru 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 Iru dashboard is at acme.kandji.io, your API domain is **acme.api.kandji.io**. EU tenants use **acme.api.eu.kandji.io**. The iru.com equivalents - **acme.api.iru.com** (or **acme.api.eu.iru.com**) - work as well; both hosts serve the same API. The API domain is not the same as your dashboard address.
    </Tip>
  </Step>
</Steps>

## Connect in Serval

<Steps>
  <Step title="Open the Iru connection form">
    In Serval, open the Iru 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 iru.com hosts are accepted too: yourcompany.api.iru.com and yourcompany.api.eu.iru.com. The field validates the format and rejects anything else with: "Must be a valid Iru API domain (e.g., yourcompany.api.kandji.io, yourcompany.api.iru.com, or yourcompany.api.eu.kandji.io)"
  </Step>

  <Step title="Enter the API Key (required)">
    Paste the full Iru 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 Iru API host - addresses ending in .api.kandji.io, .api.eu.kandji.io, .api.iru.com, or .api.eu.iru.com. Any other destination receives no credentials.

## Verifying the connection

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

1. **Test Iru Connection** - verifies authentication with a lightweight call that lists your tags. Success: "Successfully authenticated with Iru at \[your API domain]". Failure: "Unable to connect to Iru 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 Iru integration settings."
2. **List Iru Devices** - lists up to 100 devices and counts them. Success: "Successfully listed \[number] devices from Iru". Failure: "Unable to list devices from Iru." plus a specific reason.
3. **List Iru Blueprints** - lists your blueprints and counts them. Success: "Successfully listed \[number] blueprints from Iru". Failure: "Unable to list blueprints from Iru." plus a specific reason.

If Iru itself is having a temporary problem, the device and blueprint checks append: "Iru returned a server error. This is likely a temporary issue with Iru's API - please try again later." The connection check words it as: "Iru 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 Iru: 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">
    Iru 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 Iru 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 Iru. Please ensure the token has been granted the necessary permissions in Iru.") Fix it in Iru 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 Iru resource was not found. This may indicate missing permissions or incorrect API domain configuration." Verify both the token's endpoint permissions in Iru 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, and the iru.com equivalents (acme.api.iru.com, acme.api.eu.iru.com) work as well. The form rejects anything else with: "Must be a valid Iru API domain (e.g., yourcompany.api.kandji.io, yourcompany.api.iru.com, or yourcompany.api.eu.kandji.io)" - and Serval only attaches your token to requests bound for valid Iru 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 Iru integration settings." The device and blueprint checks word the same problem as: "The Iru API token may be invalid or expired. Please verify your API token is correct." Iru 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 Iru 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 Iru Computers" workflow syncs Mac devices only. Non-Mac Apple devices are not ingested as assets, but they remain fully reachable through the "Iru API request" action and the inventory and compliance workflows.
  </Accordion>

  <Accordion title="A custom device-listing workflow returns at most 300 devices">
    Iru returns list results in pages, with a maximum of 300 records per page. Serval's prebuilt workflows (including Get All Iru 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>
</AccordionGroup>

***

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