Skip to main content

Overview

Formal’s Mobile Device Management (MDM) integration rolls out the Formal Endpoint to your managed devices. It also syncs enrolled devices and their assigned users into Formal.

Supported MDM Providers

Formal supports Kandji, Fleet, Jamf Pro, Mosyle, and Rippling for both endpoint rollout and MDM integrations.

Endpoint Rollout

Go to MDM and click Set Up Endpoint Rollout. The dialog walks you through selecting your provider, downloading deployment files, and following setup instructions in your MDM console.

Connect Your MDM

Create an MDM integration to sync enrolled devices and their assigned users from your MDM into Formal. Formal uses this list to identify the user behind a device by its serial number, for example when the device attests its identity or signs in without a user login. Option 1: Control Plane
  1. Go to MDM
  2. Click Create Integration
  3. Select Kandji, Fleet, Jamf Pro, Mosyle, or Rippling
  4. Enter your MDM API credentials (see API credentials and permissions)
  5. Click Save
Option 2: Terraform Use the formal_integration_mdm resource with the block for your provider:
Mosyle signs in on every API call, so it needs an access token plus the credentials of a Mosyle user with API access:
See the Terraform provider for Kandji and Jamf Pro examples.

API credentials and permissions

Formal only reads from your MDM. It lists devices and reads each device’s serial number and assigned user’s email. It never writes to your MDM, so give its credentials read-only access to devices and nothing else.

Kandji

In Kandji, open Settings > Access and click Add API Token. When you configure the token’s permissions, enable only List Devices (GET /api/v1/devices) under Device Information. Use the tenant API URL shown on the same page. See Kandji API and the API reference.

Fleet

Create an API-only user with the global Observer role and use its API token. Observer is read-only and can view all hosts. A team-level role only sees that team’s hosts. See Fleet roles and permissions. Formal reads the user email from each host’s identity provider (mdm_idp_accounts) device mapping.

Jamf Pro

In Jamf Pro, open Settings > System > API roles and clients. Create an API role with only the Read Computers privilege, then create an API client with that role and generate a client secret. Formal calls only POST /api/v1/oauth/token and GET /api/v1/computers-inventory, which requires Read Computers. See API roles and clients.

Mosyle

Mosyle requires three values: Formal only lists Macs and reads each one’s serial number and assigned user’s email. api_url defaults to https://businessapi.mosyle.com. Use https://managerapi.mosyle.com for Mosyle Manager.
Formal reads the assigned user’s email from each Mac’s Mosyle record. A Mac with no assigned user cannot be mapped to a Formal user, so assign devices to users in Mosyle before relying on automatic device login.

Rippling

In Rippling, open Tools > Developer > API Tokens and create a token with API version 2025-08-01. It only needs the devices.read and workers.read scopes, to read each device’s serial number and assigned worker’s work email. See Rippling REST API. Verify: After saving, open the integration detail page and confirm devices appear under Devices.

Next Steps

Formal Endpoint

Install the Formal Endpoint

Terraform Provider

Configure MDM integrations with Terraform

MDM

Set up endpoint rollout and MDM integrations