Docs

Integrations / Devices / Iru (formerly Kandji)

Get Device Information

Retrieves detailed device information from Kandji by user email, serial number, or device ID

Retrieves detailed device information from Kandji, including hardware specifications, user assignments, operating system details, and installed applications. This tool supports multiple search methods and can be used for device troubleshooting, inventory management, and compliance verification.

Overview

The Kandji Get Device Information tool allows Risotto to automatically retrieve comprehensive device data from your Kandji tenant. This is useful for:

  • Device Troubleshooting: Get full hardware and software details to diagnose issues
  • User Support: Look up a user's assigned device(s) to verify configuration
  • Inventory Management: Retrieve device specifications and installed applications
  • Compliance Verification: Check OS versions, installed apps, and management status

How It Works

When configured, this tool can search for devices using three methods:

  1. User Email - Find all devices assigned to a specific user
  2. Serial Number - Look up a specific device by its hardware serial number
  3. Device ID - Direct lookup using Kandji's internal device ID

The tool returns detailed information including:

  • Device name, model, and serial number
  • Operating system version and platform
  • User assignment (name and email)
  • Hardware specifications and model identifier
  • Kandji management details (last check-in time, enrollment status)
  • Installed applications (optional)

Prerequisites

Before setting up this tool, you need:

1. Kandji Tenant Access

Administrative access to your Kandji tenant with permission to create API tokens.

2. API Subdomain

Your Kandji subdomain, which is part of your API URL:

  • US region: https://yourcompany.api.kandji.io (subdomain: yourcompany)
  • EU region: https://yourcompany.api.eu.kandji.io (subdomain: yourcompany)

You can find your API URL in Settings > Access in the Kandji web application.

3. API Token with Device Read Permissions

A bearer token with permissions to read device information from the Kandji API.

Step-by-Step Setup

Step 1: Navigate to API Token Settings

  1. Log into your Kandji tenant as an administrator
  2. Click Settings (gear icon) in the left sidebar
  3. Click the Access tab
  4. Scroll down to the API Tokens section

Step 2: Create a New API Token

  1. Click the Add API Token button
  2. In the modal that appears, provide:
    • Name: Risotto Integration (or your preferred name)
    • Description: API token for Risotto device information retrieval (optional but recommended)
  3. Click Create

Step 3: Copy the API Token

After creating the token, Kandji will display a modal with the API token.

  1. Click the visibility symbol (eye icon) to reveal the token, or
  2. Click the Copy Token button to copy it to your clipboard
  3. Store the token securely - you will not be able to view it again

Step 4: Configure Token Permissions

After creating the token, you need to assign the appropriate permissions for device read access.

  1. In the API Tokens list, find your newly created token
  2. Click on the token name to view details
  3. Click the Permissions tab
  4. Under Devices, select all Read permissions (API GET operations)
    • This grants read-only access to device inventory data
    • Specifically includes access to:
      • GET /api/v1/devices (list and search devices)
      • GET /api/v1/devices/{device_id}/details (get device details)
      • GET /api/v1/devices/{device_id}/apps (get installed apps)
  5. Click Save

Step 5: Identify Your Region and Subdomain

  1. While in Settings > Access, note your API URL at the top of the page
  2. Identify your region:
    • If URL contains .api.kandji.io → Region: US
    • If URL contains .api.eu.kandji.io → Region: EU
  3. Identify your subdomain (the part before .api.kandji.io or .api.eu.kandji.io)
    • Example: For acme.api.kandji.io, the subdomain is acme

Step 6: Connect Iru (Kandji) in Risotto

Skip this step if Iru is already connected for your organization.

  1. In the Risotto dashboard, navigate to Settings > Integrations > Iru
  2. On the Iru card, click Connect
  3. Enter your Kandji API details:
    • Subdomain: Your Kandji subdomain (without the API domain), for example acme
    • API Token: The bearer token from Step 3
    • Region: United States (US) or European Union (EU)
  4. Click Save

Step 7: Enable the Tool in Risotto

  1. Select Tools in the sidebar
  2. In the Tool groups list, select Iru
  3. Find Iru Get Device Information and click Enable
  4. Optionally, open the tool and click Edit to change its settings:
    • Restrict to Requestor Only: Only operate on devices assigned to the ticket requestor. On by default.
  5. Click Save

Configuration Options

When using this tool in a runbook, you can specify:

Search Parameters (at least one required):

  • Requester Email - Email address of the device owner (use when device is assigned to a user)
  • Serial Number - Device serial number (use for unassigned devices or when user is unknown)
  • Device ID - Kandji device ID for direct lookup (use when you have the internal ID)

Output Options:

  • Include Apps - Whether to include the list of installed applications (default: false)
  • Return Device ID Only - Return only the device ID without full details (default: false, useful for chaining with other tools)

Usage Examples

Example 1: Look up device by user email

Request:

"Get device information for john.smith@company.com"

What Happens:

  1. Searches Kandji for devices assigned to john.smith@company.com
  2. Returns detailed device information including hardware specs and user assignment
  3. If multiple devices are found, returns a list of all devices with instructions to use serial number for specific details

Example 2: Look up device by serial number

Request:

"Get device details for serial number C02XY1ZHJG5H"

What Happens:

  1. Searches Kandji for device with matching serial number
  2. Returns complete device information including assigned user (if any)

Example 3: Get device info with installed applications

Request:

"Get device info for sarah.jones@company.com including installed apps"

What Happens:

  1. Searches for device(s) assigned to sarah.jones@company.com
  2. Returns device information plus complete list of installed applications with versions

Response Format

The tool returns device information as a JSON object:

{
  "device_id": "uuid-12345-abcde",
  "search_identifier": "user@company.com",
  "device_info": {
    "device_name": "Johns-MacBook-Pro",
    "model": "MacBook Pro (14-inch, 2023)",
    "serial_number": "C02XY1ZHJG5H",
    "os_version": "14.2.1",
    "platform": "Mac",
    "last_check_in": "2024-01-15T10:30:00.000Z",
    "assigned_user": {
      "email": "john.smith@company.com",
      "name": "John Smith"
    },
    "blueprint_name": "Standard MacBook Configuration",
    "enrollment_date": "2023-06-15T14:20:00.000Z"
  },
  "apps": [
    {
      "app_name": "Slack",
      "bundle_id": "com.tinyspeck.slackmacgap",
      "version": "4.36.140"
    }
  ]
}

When Multiple Devices Are Found

If a user has multiple devices assigned, the response includes a summary list:

{
  "multiple_devices_found": true,
  "device_count": 2,
  "search_identifier": "user@company.com",
  "devices": [
    {
      "device_id": "uuid-12345",
      "device_name": "Johns-MacBook-Pro",
      "serial_number": "C02XY1ZHJG5H",
      "platform": "Mac"
    },
    {
      "device_id": "uuid-67890",
      "device_name": "Johns-MacBook-Air",
      "serial_number": "C02AB2CDJG5K",
      "platform": "Mac"
    }
  ],
  "message": "Found 2 devices for user@company.com. Please use device_id or serial_number to get details for a specific device."
}

Error Messages

Authentication Errors

  • Authentication failed. Please check Kandji API token. - API token is invalid, expired, or has been revoked

Not Found Errors

  • No device found for {email}. - No devices assigned to that user
  • No device found with serial number {serial}. - Serial number not found in Kandji
  • No device found with ID {id}. - Device ID doesn't exist

Configuration Errors

  • Iru API token not configured. Please set up Iru in Settings > Integrations > Iru. - API token is missing from the Iru connection in Settings > Integrations > Iru
  • Iru subdomain not configured. Please set up Iru in Settings > Integrations > Iru. - Subdomain is missing from the Iru connection in Settings > Integrations > Iru

Other Errors

  • Rate limit exceeded. Please try again later. - API rate limit reached (10,000 requests per hour)
  • At least one of requester_email, serial_number, or device_id must be provided. - No search parameter provided

Troubleshooting

"Authentication failed. Please check Kandji API token."

Possible Causes:

  • API token is incorrect or incomplete
  • API token has been revoked
  • Admin user who created the token has been removed from Kandji

Solution:

  1. Verify the API token in Risotto matches the token from Kandji
  2. Check if the token still exists in Settings > Access > API Tokens
  3. If the token was deleted or the admin removed, create a new token following Steps 2-4

"No device found for {email}"

Possible Causes:

  • User email is misspelled
  • Device is not assigned to a user in Kandji
  • Device is not enrolled in Kandji

Solution:

  1. Verify the email address is correct
  2. Check in Kandji if the device exists and has a user assigned
  3. Try searching by serial number instead

Permission Errors

Symptoms:

  • Authentication succeeds but queries fail with 403 Forbidden errors
  • Error messages about insufficient permissions

Solution:

  1. Go to Settings > Access > API Tokens
  2. Click on your API token name
  3. Click the Permissions tab
  4. Ensure all Read permissions under Devices are selected
  5. Click Save

Incorrect Region or Subdomain

Symptoms:

  • Connection timeouts or DNS resolution errors
  • 404 errors when trying to access API

Solution:

  1. Verify your region setting (us or eu) matches your Kandji tenant
  2. Check your subdomain in Settings > Access
  3. Ensure the subdomain doesn't include .api.kandji.io - just the subdomain portion

Security Considerations

1. API Token Security

  • API tokens are bearer tokens that grant programmatic access to your Kandji tenant
  • Tokens are only displayed once during creation
  • Store tokens securely and never commit to version control
  • Risotto encrypts API tokens at rest

2. Least Privilege

Only grant the minimum permissions needed:

  • For read-only device information, only Device Read permissions are required
  • Avoid granting write, update, or delete permissions unless specifically needed
  • Create separate tokens for different integrations or purposes

3. Token Lifecycle Management

  • Review active API tokens regularly in Settings > Access
  • Revoke unused or obsolete tokens
  • Rotate tokens periodically (recommended every 90 days)
  • If a token is compromised, revoke it immediately and create a new one

4. Admin Account Dependencies

Best Practice: Create a dedicated service account or use a shared admin account for API token creation to avoid disruption when individual admins leave.

5. Audit Logging

All API operations are logged in Kandji:

  • Review API access logs in Settings > Access > API Logs
  • Monitor for suspicious activity or unexpected usage patterns
  • Track which integrations are using which tokens

API Rate Limits

Kandji implements API rate limiting to ensure service stability:

  • Rate Limit: 10,000 requests per hour per customer tenant
  • Scope: Rate limit applies to all API tokens for your tenant combined

If you encounter rate limit errors:

  1. The tool will return: "Rate limit exceeded. Please try again later."
  2. Wait until the next hour for the limit to reset
  3. Review your API usage patterns to optimize request frequency
  4. Consider caching frequently accessed data
  5. Contact Kandji support if limits are too restrictive for your use case

Important Notes

Token Management

  • Multiple API tokens can be created with varying levels of access
  • Each token has its own unique key and privileges
  • Token permissions can be modified after creation via the Permissions tab
  • Revoking a token prevents all future access using that token

API Endpoints Used

This tool uses the following Kandji API v1 endpoints:

  • GET /api/v1/devices?user_email={email} - Search devices by user email
  • GET /api/v1/devices?serial_number={serial} - Search devices by serial number
  • GET /api/v1/devices/{device_id}/details - Get detailed device information
  • GET /api/v1/devices/{device_id}/apps - Get installed applications

Authentication Method

The Kandji API uses Bearer token authentication:

Authorization: Bearer {api_token}

All requests include the API token in the Authorization header. The tool handles authentication automatically.

  • Kandji Policy Deployment: Deploy configuration profiles and scripts (coming soon)
  • Kandji Device Lock: Remotely lock lost or stolen devices (coming soon)
  • Device Compliance Checker: Verify devices meet security requirements (coming soon)

Additional Resources

Something wrong or missing? Report an issue · View as Markdown