Skip to main content

​
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

Anything defined in the Iru API 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.
Tenant hostnames and the support article still use the kandji.io domain.
1

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

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

Copy the token immediately

Copy the token and store it securely, then confirm the “I have copied the token…” checkbox and click Next.
Iru never displays the cleartext token again after this screen. If you lose it, you’ll have to create a new token.
4

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

Determine your API domain

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.

​
Connect in Serval

1

Open the Iru connection form

In Serval, open the Iru integration and start a new connection.
2

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)”
3

Enter the API Key (required)

Paste the full Iru API token into the API Key password field.
4

Save the connection

Save, then verify the connection using the health checks below.
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.
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.”
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.

​
Gotchas and troubleshooting

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).
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.
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.
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.
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.
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.
Need help? Contact support@serval.com for assistance with your Iru integration.