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:
- User Email - Find all devices assigned to a specific user
- Serial Number - Look up a specific device by its hardware serial number
- 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
- Log into your Kandji tenant as an administrator
- Click Settings (gear icon) in the left sidebar
- Click the Access tab
- Scroll down to the API Tokens section
Step 2: Create a New API Token
- Click the Add API Token button
- In the modal that appears, provide:
- Name:
Risotto Integration(or your preferred name) - Description:
API token for Risotto device information retrieval(optional but recommended)
- Name:
- Click Create
Step 3: Copy the API Token
After creating the token, Kandji will display a modal with the API token.
- Click the visibility symbol (eye icon) to reveal the token, or
- Click the Copy Token button to copy it to your clipboard
- 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.
- In the API Tokens list, find your newly created token
- Click on the token name to view details
- Click the Permissions tab
- 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)
- Click Save
Step 5: Identify Your Region and Subdomain
- While in Settings > Access, note your API URL at the top of the page
- Identify your region:
- If URL contains
.api.kandji.io→ Region: US - If URL contains
.api.eu.kandji.io→ Region: EU
- If URL contains
- Identify your subdomain (the part before
.api.kandji.ioor.api.eu.kandji.io)- Example: For
acme.api.kandji.io, the subdomain isacme
- Example: For
Step 6: Connect Iru (Kandji) in Risotto
Skip this step if Iru is already connected for your organization.
- In the Risotto dashboard, navigate to Settings > Integrations > Iru
- On the Iru card, click Connect
- 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)
- Subdomain: Your Kandji subdomain (without the API domain), for example
- Click Save
Step 7: Enable the Tool in Risotto
- Select Tools in the sidebar
- In the Tool groups list, select Iru
- Find Iru Get Device Information and click Enable
- 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.
- 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:
- Searches Kandji for devices assigned to john.smith@company.com
- Returns detailed device information including hardware specs and user assignment
- 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:
- Searches Kandji for device with matching serial number
- 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:
- Searches for device(s) assigned to sarah.jones@company.com
- 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 userNo device found with serial number {serial}.- Serial number not found in KandjiNo 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 > IruIru 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:
- Verify the API token in Risotto matches the token from Kandji
- Check if the token still exists in Settings > Access > API Tokens
- 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:
- Verify the email address is correct
- Check in Kandji if the device exists and has a user assigned
- Try searching by serial number instead
Permission Errors
Symptoms:
- Authentication succeeds but queries fail with 403 Forbidden errors
- Error messages about insufficient permissions
Solution:
- Go to Settings > Access > API Tokens
- Click on your API token name
- Click the Permissions tab
- Ensure all Read permissions under Devices are selected
- Click Save
Incorrect Region or Subdomain
Symptoms:
- Connection timeouts or DNS resolution errors
- 404 errors when trying to access API
Solution:
- Verify your region setting (us or eu) matches your Kandji tenant
- Check your subdomain in Settings > Access
- 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:
- The tool will return: "Rate limit exceeded. Please try again later."
- Wait until the next hour for the limit to reset
- Review your API usage patterns to optimize request frequency
- Consider caching frequently accessed data
- 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 emailGET /api/v1/devices?serial_number={serial}- Search devices by serial numberGET /api/v1/devices/{device_id}/details- Get detailed device informationGET /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.
Related Tools
- 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