Docs

Integrations / Devices / Jamf Pro

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.

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

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)
  1. 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:

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

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

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)
  • JAMF Pro Policy Execution: Trigger JAMF policies on 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