# 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

> **Warning:** The API token is only displayed once during creation. Save it immediately in a
> secure location. If you lose it, you'll need to create a new token.

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

> **Tip:** For least-privilege access, only grant Read permissions for Devices. Avoid
> granting Write, Update, or Delete permissions unless specifically needed for
> other integrations.

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

```json
{
  "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:

```json
{
  "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

> **Warning:** If an admin user is removed from Kandji after creating an API token, that
> token will also be removed automatically.

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

> **Warning:** API tokens are tied to the admin user who created them. If that admin is
> removed from Kandji, the token will be automatically revoked.

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

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

- [Kandji API Documentation](https://api-docs.kandji.io/)
- [Kandji Support: API Overview](https://support.kandji.io/kb/kandji-api)
- [Integrating Third-Party Apps Using the Kandji API](https://support.kandji.io/kb/integrating-third-party-apps-using-the-kandji-api)
- [APIs and Apple Device Management Guide](https://www.kandji.io/blog/apis-and-device-management-a-guide-for-apple-it)
- [Kandji Support Portal](https://support.kandji.io/)

Source: https://www.tryrisotto.com/docs/integrations/tools/kandji/get_device_information
