# Jamf

Connecting Jamf gives SureCloud read access to your Jamf Pro instance's managed device inventory, configuration profile assignments, policy deployment status, and security compliance data. SureCloud monitors MDM enrolment coverage to identify devices that are no longer managed, checks FileVault encryption status across the macOS fleet, verifies that security-relevant configuration profiles are deployed to the correct device groups, and tracks OS patch levels to surface devices running outdated software. This provides continuous evidence that your Apple device estate is managed, encrypted, and maintained in line with your security requirements.

{% hint style="info" %}
SureCloud connects to Jamf Pro using OAuth 2.0 with the client credentials flow. You create an API client in Jamf Pro and provide the client ID and secret to SureCloud. For older Jamf Pro versions that do not support API clients (pre-10.49), a dedicated service account with a Bearer Token is used instead.
{% endhint %}

## Authentication and setup

{% tabs %}
{% tab title="Jamf Pro 10.49+ (OAuth 2.0 — recommended)" %}
{% stepper %}
{% step %}

#### Create an API client in Jamf Pro

In Jamf Pro, navigate to **Settings → System → API Roles and Clients → API Clients → New**.

* **Display name**: `SureCloud CCM`
* **Enable API client**: checked
* **Access token lifetime**: 30 minutes (SureCloud refreshes automatically)

Assign the `SureCloud Read Only` API role (create this in the next step if it does not exist). Click **Save** and copy the **Client ID**.

Then click **Generate Client Secret**, copy the secret value immediately, and click **Save**.

{% hint style="warning" %}
The client secret is only displayed once. If it is lost, generate a new secret and update it in **SureCloud → Integrations → Jamf → Edit Connection**.
{% endhint %}
{% endstep %}

{% step %}

#### Create a read-only API role

In **Settings → System → API Roles and Clients → API Roles → New**, create a role named `SureCloud Read Only` with the following privileges:

| Privilege                   | Purpose                                                       |
| --------------------------- | ------------------------------------------------------------- |
| Read Computers              | Read macOS device inventory and management state              |
| Read Mobile Devices         | Read iOS/iPadOS device inventory                              |
| Read Computer Management    | Read policy assignments and configuration profile deployments |
| Read Configuration Profiles | Read configuration profile definitions                        |
| Read Users                  | Read Jamf user accounts                                       |
| Read Categories             | Read object categories (used for scoping)                     |
| Read Computer Groups        | Read static and smart device groups                           |
| Read Mobile Device Groups   | Read mobile device groups                                     |

Click **Save**.
{% endstep %}

{% step %}

#### Enter credentials in SureCloud

In SureCloud, navigate to **Integrations → Jamf → Connect** and provide:

* **Jamf Pro URL** (e.g. `https://yourcompany.jamfcloud.com`)
* **Client ID**
* **Client Secret**

Click **Test Connection**, then **Save**.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Jamf Pro pre-10.49 (Bearer Token)" %}
{% stepper %}
{% step %}

#### Create a dedicated service account

In Jamf Pro, navigate to **Settings → System → User Accounts and Groups → New** and create a user account:

* **Username**: `surecloud-ccm`
* **Privilege set**: Custom
* **Access level**: Full access

Assign read-only privileges for Computers, Mobile Devices, Configuration Profiles, and Computer Management. Do not assign any create, edit, or delete privileges.
{% endstep %}

{% step %}

#### Enter credentials in SureCloud

In SureCloud, navigate to **Integrations → Jamf → Connect (Legacy)** and provide:

* **Jamf Pro URL**
* **Username**: `surecloud-ccm`
* **Password**

SureCloud exchanges the credentials for a session Bearer Token using the `/api/v1/auth/token` endpoint and refreshes it automatically before expiry.

{% hint style="warning" %}
If the service account password is changed in Jamf Pro without being updated in SureCloud, the token refresh will fail and data collection will stop. Update the password in **SureCloud → Integrations → Jamf → Edit Connection**.
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

## Endpoints

| API Call                                           | Use Case                                                                                           |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `GET /api/v1/computers-inventory`                  | Enumerate all managed macOS computers with management state, OS version, and last check-in         |
| `GET /api/v1/computers-inventory/{id}`             | Retrieve full computer record including FileVault status, disk encryption, and certificate details |
| `GET /api/v1/computers-inventory-detail/{id}`      | Read detailed compliance data including security settings and policy receipts                      |
| `GET /api/v1/mobile-devices`                       | Enumerate managed iOS and iPadOS devices with enrolment state and compliance status                |
| `GET /api/v1/mobile-devices/{id}/detail`           | Read per-device passcode compliance, encryption, and management profile state                      |
| `GET /api/v1/configuration-profiles`               | List macOS configuration profiles and their scope and deployment state                             |
| `GET /api/v1/mobile-device-configuration-profiles` | List iOS configuration profiles and deployment scope                                               |
| `GET /api/v1/computer-groups`                      | Enumerate computer smart groups and static groups for scoping analysis                             |
| `GET /api/v1/policies`                             | List Jamf policies and their trigger, scope, and execution frequency                               |
| `GET /api/v1/disk-encryption-configurations`       | Read FileVault disk encryption configuration definitions                                           |

## Pagination

The Jamf Pro API v1 uses page-based pagination via `page` and `page-size` query parameters. SureCloud requests pages of up to 100 records and increments the `page` number until fewer results than `page-size` are returned.

```json
{
  "totalCount": 1842,
  "results": [
    {
      "id": "1",
      "udid": "ABC123...",
      "name": "Alice's MacBook Pro",
      "managementState": "managed",
      "osVersion": "14.4.1"
    }
  ]
}
```

## Required permissions

All required permissions are **Read** only as defined in the API role created during setup. SureCloud does not require any create, update, or delete privileges in Jamf Pro.

## Polling frequency

| Data type                              | Collection interval |
| -------------------------------------- | ------------------- |
| Computer and mobile device inventory   | 24 hours            |
| FileVault and encryption status        | 24 hours            |
| Configuration profile deployment       | 24 hours            |
| Policy assignment and execution status | 24 hours            |
| Device group membership                | 24 hours            |

## Troubleshooting

<details>

<summary>FileVault encryption status shows as unknown for some devices</summary>

FileVault status is reported in the computer's detailed inventory record under the `diskEncryption` object. If this field is absent or shows as unknown, the macOS device may not have reported its encryption state to Jamf Pro since the last Jamf inventory update.

Force an inventory update on the affected device via **Jamf Pro → Computers → \[Device] → Management → Update Inventory**, or push an inventory update policy. SureCloud will reflect the updated status on the next polling cycle.

</details>

<details>

<summary>Configuration profiles are listed but deployment scope is not visible</summary>

Configuration profile scope (target devices, groups, departments) requires the **Read Configuration Profiles** and **Read Computer Groups** privileges on the API role. If scope data is missing, confirm both privileges are assigned to the `SureCloud Read Only` role in **Jamf Pro → Settings → API Roles**.

</details>

<details>

<summary>Mobile devices are not appearing despite being managed in Jamf</summary>

Mobile device collection requires the **Read Mobile Devices** privilege. If the API role only includes computer-related privileges, mobile devices will be absent from SureCloud's inventory.

Update the `SureCloud Read Only` role to include **Read Mobile Devices** and **Read Mobile Device Groups**, then trigger a manual refresh from **SureCloud → Integrations → Jamf → Edit Connection**.

</details>

<details>

<summary>Test Connection fails with "401 Unauthorized" for OAuth 2.0 connections</summary>

The client secret may have been regenerated in Jamf Pro without being updated in SureCloud, or the API client may have been disabled.

1. In **Jamf Pro → Settings → API Clients**, confirm the `SureCloud CCM` client is enabled.
2. If a new secret was generated, update it in **SureCloud → Integrations → Jamf → Edit Connection → Client Secret**.
3. Confirm the Jamf Pro version is 10.49 or later. Earlier versions do not support API client OAuth 2.0 — use the Bearer Token tab in the setup guide instead.

</details>

<a href="https://developer.jamf.com/jamf-pro/reference/jamf-pro-api" class="button secondary">Jamf Pro API reference</a> <a href="https://learn.jamf.com/bundle/jamf-pro-documentation-current/page/API_Roles_and_Clients.html" class="button secondary">Jamf API Roles and Clients documentation</a>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/jamf.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.