Skip to main content

​
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

Anything defined in the Kandji API 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.
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.
1

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

Determine your API domain

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.

​
Connect in Serval

1

Open the Kandji connection form

In Serval, open the Kandji 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 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)”
3

Enter the API Key (required)

Paste the full Kandji 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 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.”
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.

​
Gotchas and troubleshooting

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