# Get Device Information

Retrieves detailed device information from JAMF Pro by user email, serial number, or computer ID

Retrieves detailed device information from JAMF Pro, 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 JAMF Pro Get Device Information tool allows Risotto to automatically retrieve comprehensive device data from your JAMF Pro instance. 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. **Computer ID** - Direct lookup using JAMF Pro's internal computer ID

The tool returns detailed information including:

- Device name, model, and serial number
- Operating system version and platform
- User assignment (name, email, department, position)
- Hardware specifications (processor, RAM, model identifier)
- JAMF management details (last contact time, binary version)
- Installed applications (optional)

## Prerequisites

Before setting up this tool, you need:

### 1. JAMF Pro Server URL

Your JAMF Pro server URL, typically in one of these formats:

- `https://yourcompany.jamfcloud.com` (JAMF Cloud)
- `https://jamf.yourcompany.com` (Self-hosted)

### 2. API Client Credentials

Beginning in JAMF Pro version 10.49.0, the recommended authentication method is **API Client Credentials** (OAuth-based). This is more secure than username/password authentication as API clients cannot access the JAMF Pro user interface.

> **Note:** JAMF Pro also supports Basic Authentication (username/password), but API
> Client Credentials are recommended for security and best practices.

## Step-by-Step Setup

### Step 1: Create an API Role

API Roles define which API endpoints and privileges an API Client can access.

1. Log into your JAMF Pro server as an administrator
2. Navigate to **Settings** (gear icon) > **System** > **API Roles and Clients**
3. Click the **API Roles** tab
4. Click **+ New**
5. Configure the API Role:
   - **Display Name**: `Risotto Computer Inventory Reader` (or your preferred name)
   - **Privileges**: Select **Read Computers**
     - This privilege grants read access to computer inventory data
     - Required for the `/api/v1/computers-inventory` and `/api/v1/computers-inventory-detail` endpoints
6. Click **Save**

> **Tip:** For least-privilege access, only grant the "Read Computers" privilege. If you
> need to support other JAMF tools in the future, you can create additional API
> Roles or add more privileges.

### Step 2: Create an API Client

API Clients use the privileges defined in API Roles to authenticate and access the API.

1. Still in **Settings** > **System** > **API Roles and Clients**
2. Click the **API Clients** tab
3. Click **+ New**
4. Configure the API Client:
   - **Display Name**: `Risotto Integration` (or your preferred name)
   - **API Roles**: Select the API Role you created in Step 1 (`Risotto Computer Inventory Reader`)
   - **Enabled**: Check this box to activate the client
5. Click **Save**

### Step 3: Generate Client Secret

After creating the API Client, you must generate a client secret to complete authentication setup.

1. Find your newly created API Client in the list
2. Click on the client name to view details
3. Click **Generate Client Secret** (or **Rotate Client Secret** if regenerating)
4. A modal will display:
   - **Client ID**: Copy this value (you'll need it for Risotto configuration)
   - **Client Secret**: Copy this value **immediately** (it will only be shown once)

> **Warning:** The client secret is only displayed once when generated. Save it securely
> immediately. If you lose it, you'll need to rotate the secret to generate a
> new one.

5. Store both the Client ID and Client Secret securely

### Step 4: Connect JAMF Pro in Risotto

Skip this step if JAMF Pro is already connected for your organization.

1. In the Risotto dashboard, navigate to **Settings > Integrations > Jamf**
2. On the **JAMF Pro** card, click **Connect**
3. Enter your JAMF Pro credentials:
   - **Server URL**: Your JAMF Pro server URL (without trailing slash), for example `https://yourcompany.jamfcloud.com`
   - **Client ID**: The Client ID from Step 3
   - **Client Secret**: The Client Secret from Step 3
4. Click **Save**

### Step 5: Enable the Tool in Risotto

1. Select **Tools** in the sidebar
2. In the **Tool groups** list, select **Jamf**
3. Find **JAMF Pro 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)
- **Computer ID** - JAMF Pro computer 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 Computer ID Only** - Return only the computer 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 JAMF Pro 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 JAMF Pro 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
{
  "computer_id": "1234",
  "search_identifier": "user@company.com",
  "device_info": {
    "general": {
      "name": "Johns-MacBook-Pro",
      "platform": "Mac",
      "osVersion": "14.2.1",
      "lastContactTime": "2024-01-15T10:30:00.000Z",
      "managementId": "abc-123-def-456"
    },
    "userAndLocation": {
      "username": "john.smith",
      "realName": "John Smith",
      "email": "john.smith@company.com",
      "department": "Engineering",
      "position": "Software Engineer"
    },
    "hardware": {
      "serialNumber": "C02XY1ZHJG5H",
      "model": "MacBook Pro (14-inch, 2023)",
      "modelIdentifier": "Mac14,9",
      "processorType": "Apple M2 Pro",
      "totalRamMegabytes": 16384
    }
  },
  "applications": [
    {
      "name": "Slack",
      "version": "4.36.140",
      "bundleId": "com.tinyspeck.slackmacgap"
    }
  ]
}
```

### 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": [
    {
      "computer_id": "1234",
      "device_name": "Johns-MacBook-Pro",
      "serial_number": "C02XY1ZHJG5H",
      "model": "MacBook Pro (14-inch, 2023)"
    },
    {
      "computer_id": "5678",
      "device_name": "Johns-MacBook-Air",
      "serial_number": "C02AB2CDJG5K",
      "model": "MacBook Air (13-inch, 2022)"
    }
  ],
  "message": "Found 2 devices for user@company.com. Please use computer_id or serial_number to get details for a specific device."
}
```

## Error Messages

### Authentication Errors

- `Authentication failed. Please check JAMF Pro API credentials.` - Client ID or secret is incorrect, or API client is disabled

### 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 JAMF Pro
- `No device found with ID {id}.` - Computer ID doesn't exist

### Configuration Errors

- `JAMF Pro server URL not configured.` - Server URL is missing from the Jamf connection in **Settings > Integrations > Jamf**
- `JAMF Pro client ID not configured.` - Client ID is missing
- `JAMF Pro client secret not configured.` - Client secret is missing

### Other Errors

- `Rate limit exceeded. Please try again later.` - Too many API requests, wait and retry
- `At least one of requester_email, serial_number, or computer_id must be provided.` - No search parameter provided

## Troubleshooting

### "Authentication failed. Please check JAMF Pro API credentials."

**Possible Causes:**

- Client ID or Client Secret is incorrect
- API Client is disabled in JAMF Pro
- Client Secret has been rotated and credentials need to be updated

**Solution:**

1. Verify the Client ID and Secret in Risotto match what's shown in JAMF Pro
2. Check that the API Client is enabled in **Settings** > **System** > **API Roles and Clients**
3. If you've rotated the secret, update the credentials in Risotto

### "No device found for {email}"

**Possible Causes:**

- User email is misspelled
- Device is not assigned to a user in JAMF Pro
- Device is not enrolled in JAMF Pro

**Solution:**

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

### "Read Computers" Privilege Missing

**Symptoms:**

- Authentication succeeds but queries fail with permission errors
- 403 Forbidden errors in logs

**Solution:**

1. Go to **Settings** > **System** > **API Roles and Clients**
2. Edit your API Role
3. Ensure **Read Computers** privilege is selected
4. Save the role
5. **Important**: Generate a new client secret for the change to take effect

> **Warning:** When you modify which API Roles are assigned to an API Client, you must
> generate a new client secret for the changes to take effect. Simply changing
> the role privileges does not require secret rotation.

## Security Considerations

### 1. API Client vs. Username/Password

API Client Credentials (OAuth) provide several security advantages over Basic Authentication:

- API Clients cannot access the JAMF Pro web interface
- No risk of user account lockout affecting API access
- Easier credential rotation without affecting user accounts
- Clear audit trail of API vs. user actions

### 2. Least Privilege

Only grant the minimum privileges needed:

- For read-only device information, only "Read Computers" is required
- Avoid granting write permissions unless specifically needed
- Use separate API Clients for different integrations or purposes

### 3. Credential Storage

- Risotto encrypts API credentials at rest
- Client secrets are only displayed once during generation
- Store credentials securely and never commit to version control
- Rotate credentials regularly (recommended every 90 days)

### 4. Audit Logging

All API operations are logged in:

- Risotto's execution logs
- JAMF Pro's API access logs (**Settings** > **System** > **API Access Logs**)
- Review logs regularly for suspicious activity

## API Rate Limits

JAMF Pro may implement rate limits on API requests. If you encounter rate limit errors:

1. The tool will return: "Rate limit exceeded. Please try again later."
2. Wait a few minutes before retrying
3. Consider reducing the frequency of automated queries
4. Contact JAMF support if rate limits are too restrictive for your use case

## Important Notes

### Token Management

The tool automatically manages bearer tokens:

- Tokens are obtained using client credentials
- Tokens are cached and automatically refreshed before expiry
- Token lifetime is determined by JAMF Pro (typically 30 minutes)
- No manual token management is required

### API Version

This tool uses the JAMF Pro API v1 endpoints:

- `GET /api/v1/computers-inventory` - Search for computers
- `GET /api/v1/computers-inventory-detail/{id}` - Get detailed computer information
- `POST /api/v1/auth/token` - Obtain bearer token (OAuth)

> **Note:** These endpoints have a deprecation date of 2025-06-30. Monitor JAMF Developer
> documentation for updates and migration paths to newer API versions.

## Related Tools

- **JAMF Pro Policy Execution**: Trigger JAMF policies on devices (coming soon)
- **Device Compliance Checker**: Verify devices meet security requirements (coming soon)

## Additional Resources

- [JAMF Pro API Documentation](https://developer.jamf.com/jamf-pro/docs)
- [JAMF Pro API Roles and Clients Guide](https://www.jamf.com/blog/understanding-jamf-pro-api-roles-and-clients/)
- [Client Credentials Authentication](https://developer.jamf.com/jamf-pro/docs/client-credentials)
- [API Privileges and Deprecations](https://developer.jamf.com/jamf-pro/docs/privileges-and-deprecations)
- [JAMF Learning Hub](https://learn.jamf.com/)

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