> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Connect Jamf Pro to Ravenna using OAuth client credentials by creating an API role and client in your Jamf Pro server administration settings.

<Info>Connect to Jamf Pro using OAuth client credentials</Info>

This guide walks you through creating an API client in Jamf Pro and connecting it to Ravenna.

## Prerequisites

Before you begin, ensure you have:

* Jamf Pro instance (Jamf Cloud or self-hosted)
* Admin access to Jamf Pro
* Your Jamf Pro server URL

## Setup guide

### Create API client in Jamf Pro

<Steps>
  <Step title="Navigate to API settings">
    1. Sign in to your Jamf Pro web interface
    2. Navigate to **Settings** > **System** > **API Roles and Clients**
  </Step>

  <Step title="Create API role">
    1. Click the **API Roles** tab
    2. Click **New** to create a new role
    3. Enter the following details:
       * **Display Name**: `Ravenna Integration`
       * **Privileges**: Select the following:
         * Read Computers
         * Read Computer Inventory Collection
         * Read Users
    4. Click **Save**

    <Note>
      These are minimum required permissions for basic device lookup. For additional workflow actions, add the following privileges:

      **Lock Computer action:**

      * View MDM command information in Jamf Pro API
      * Send Computer Remote Lock Command
      * Send MDM command information in Jamf Pro API
      * Create Computers

      **Get FileVault Recovery Key action:**

      * View Disk Encryption Recovery Key
    </Note>
  </Step>

  <Step title="Create API client">
    1. Click the **API Clients** tab
    2. Click **New** to create a new client
    3. Enter the following details:
       * **Display Name**: `Ravenna`
       * **API Role**: Select the role you created in the previous step
       * **Access Token Lifetime**: 30 minutes (default)
       * **Enabled**: Yes
    4. Click **Save**
  </Step>

  <Step title="Generate client credentials">
    1. After saving, click **Generate Client Secret**
    2. Copy both the **Client ID** and **Client Secret**

    <Warning>
      The client secret is only shown once. Store it securely before closing this dialog.
    </Warning>
  </Step>
</Steps>

### Add integration in Ravenna

<Steps>
  <Step title="Navigate to integrations">
    1. Go to **Settings** > **Integrations**
    2. Find **Jamf Pro** in the Device Management section
  </Step>

  <Step title="Select Jamf Pro">
    Click **Connect** on the Jamf Pro integration card
  </Step>

  <Step title="Configure credentials">
    Provide the following information:

    <ParamField path="serverUrl" type="string" required>
      Your Jamf Pro server URL (e.g., `https://company.jamfcloud.com`)

      <Note>
        For Jamf Cloud, use your organization's Jamf Cloud URL. For self-hosted instances, use your custom domain.
      </Note>
    </ParamField>

    <ParamField path="clientId" type="string" required>
      The client ID from your Jamf Pro API client
    </ParamField>

    <ParamField path="clientSecret" type="string" required>
      The client secret you generated in Jamf Pro
    </ParamField>
  </Step>

  <Step title="Complete setup">
    Click **Connect** to complete the integration. This will:

    1. Obtain an access token using your credentials
    2. Test connectivity to your Jamf Pro server
    3. Verify API permissions
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Failed to obtain OAuth access token" icon="circle-x">
    **Cause**: Client credentials are invalid or the API client is disabled

    **Solution**:

    * Verify the client ID and secret were copied correctly
    * Check that the API client is enabled in Jamf Pro
    * Ensure the server URL is correct and accessible
    * Generate a new client secret if needed
  </Accordion>

  <Accordion title="Connection timeout error" icon="clock">
    **Cause**: Cannot reach Jamf Pro server URL

    **Solution**:

    * Verify the server URL is correct and accessible
    * Ensure the URL includes the protocol (`https://`)
    * For self-hosted instances, verify DNS resolution and firewall rules
  </Accordion>

  <Accordion title="Insufficient permissions error" icon="shield-x">
    **Cause**: API role doesn't have required permissions

    **Solution**:

    * Verify the API role includes "Read Computers" and "Read Computer Inventory Collection" permissions
    * Update the role with additional permissions if needed
    * Ensure the API client is assigned to the correct role
  </Accordion>

  <Accordion title="Device not found for user" icon="user-search">
    **Cause**: Cannot match user to a Jamf Pro device

    **Solution**:

    * Verify the device is enrolled in Jamf Pro
    * Check that User and Location information is populated on the device
    * Ensure the user's email matches the device assignment in Jamf Pro
  </Accordion>
</AccordionGroup>