MDM & Device Operations

Operate the Apple MDM channel and the cross-OS device fleet from your instance — enrol devices, lock or wipe a Mac through Apple MDM, push profiles, scope smart groups, and recover an encrypted disk with a full audit trail.

What It Does

The device console does two distinct jobs, and it is worth keeping them apart because they reach a computer in different ways. Apple MDM is the Apple channel — it locks, wipes, restarts, or profiles a Mac through Apple’s push service. The Zonitix agent is the cross-OS channel — on macOS, Linux and Windows it applies each system’s own hardening settings (the firewall on all three, Gatekeeper on a Mac) and runs queued commands (restart, install OS updates, rename; lock screen on Windows and Linux) each time the agent checks in. Some operations here go through MDM and some through the agent, and what each can do differs.

Where Apple MDM Runs

The Zonitix agent reports to your own instance. Apple MDM does not: it is a preview feature that runs from one Zonitix-hosted service, shared across customers, with each customer’s Macs in a separate tenant. When you use the Apple MDM actions on this page, your instance passes the request to that service, and the records for your enrolled Macs are held there. What it holds is in the Trust Center sub-processor list, and how your instance connects to it is on Design Philosophy. If Apple MDM is not set up for your instance, the Apple MDM panel shows that it is not connected and the Mac actions are not offered.

If something here is not working as you expect, start with When something goes wrong.

MDM Status & Enrolled Devices

Two read routes tell you whether MDM is wired up and what it sees. status aggregates three upstream calls (devices, enrollment, push cert) and reports connected only when the MDM device list returns a 2xx. MDM-enrolled Macs are folded into the main fleet inventory on a throttled (60s), best-effort sync, so they also appear under Groups and can be scoped by profiles.

Inspector checks: connected:false with configured:true means the tenant key is set but the control plane did not answer 2xx (or rejected the key — see the 502 remap). hasCert:false means no Apple push certificate is installed yet, so no command can actually reach a device even once enrolled.

Apple Push Certificate

The APNs push certificate and its private key are what let MDM reach a Mac at all. The usual path is self-serve: download the signing request from your instance, take it to Apple’s push-certificate portal, then upload the .pem Apple returns — on its own, because the MDM already holds the matching private key from the request step. If you made the key pair yourself, upload the certificate together with its key, or a .p12 with its passphrase. The MDM validates the upload and extracts the APNs topic. The invariant an inspector should verify: on upload, any private key transits app → MDM only, rests only in the MDM (never in the app database), and is never echoed back to the browser. The one deliberate exception is the key-backup route, which exports the certificate and key as a .p12 behind the destructive gate; the download is streamed through, not stored in the app, and audited.

Status codes: 400 when MDM is unconfigured, the certificate is missing, or a .p12 cannot be opened; 413 when certPem + keyPem exceeds 200,000 characters; 424 when the MDM does not answer the upload — the certificate may or may not have been installed, so reload the page to check before retrying; otherwise the MDM’s own status is returned. The upload is audited on every outcome, and the response never contains the key material you sent.

Per-Device Commands (Lock, Wipe, Power, Bootstrap)

These act on one MDM-enrolled Mac addressed by its :udid. Lock, power and bootstrap require manage_devices; wipe requires manage_device_destructive, a step-up re-authentication and a reason. All return 400 if MDM is not configured.

Each command is answered by its outcome. Lock, wipe, restart, shut down, bootstrap and raw profile install and removal are audited on every outcome. Queued, or refused by the MDM (for example a 404 for an unknown device): the MDM’s own status and body. The MDM did not answer (timeout or unreachable): 424 { error, outcome: 'error' } — the command may or may not have been queued, so check the device before retrying. The MDM answered 2xx but did not queue it: 424 { error, queued: false, outcome: 'not_queued' } — nothing was sent to the Mac. The same status rules cover lock, restart, shut down, bootstrap and raw profile install and removal. They also cover the inventory-refresh routes above, which are read-only and write no audit record. Wipe follows them too, except that its no-answer case returns 502 rather than 424. The lock-PIN, enrollment-code and enrollment-profile reads return 424 when the MDM does not answer, and write no “revealed” or “minted” audit record.

install-agent is a two-step bootstrap: it first pushes this customer’s agent config profile (server URL + reusable tenant enrollment token, so the installed agent can only ever report to your tenant), then issues InstallEnterpriseApplication pointing at your own signed pkg URL https://<API_DOMAIN>/agent/pkg. It returns 400 if API_DOMAIN is unset, because there would be no download URL to build.

The install request carries the hosted package’s SHA-256 and size, which go into the install manifest so the Mac refuses bytes that do not match. If no usable hash is stored for the package, the install relies on the installer signature alone and your instance logs a warning. If the configuration profile is not queued, the package is not sent and the route answers for the configuration step using the outcome rules above, so an agent is never installed without knowing which instance to report to. The audit record says which step was reached and whether the package hash was sent.

Enrol A Mac In Apple MDM

Enrolling a Mac in Apple MDM is separate from installing the Zonitix agent, and it is done on the Mac by the person holding it — zero-touch (DEP/ADE) enrollment is not available. In order:

1. Connect Apple MDM. In the device setup flow, the optional “Apple MDM & push certificate” step connects your instance to the MDM service. If it reports that a provisioning key is needed, that is a one-time step on our side — contact support.
2. Install your Apple push certificate (see Apple Push Certificate above). Until hasCert is true, a Mac can enrol but no command can reach it.
3. Send the Mac to your enrollment page, https://<your-instance>.zonitix.com/enroll, opened in Safari. A signed-in user gets the enrollment profile straight away. Someone without an account enters an enrollment code an admin generated: a single-use code (the dashboard shows it expiring in about 15 minutes) or a reusable one for a batch of Macs (shown as valid for 24 hours).
4. Install the profile on the Mac in System Settings → General → VPN & Device Management. The Mac then appears in the MDM device list and is folded into the main inventory.

Two things an inspector should know. The profile download needs only a valid session, not view_devices — enrolling your own Mac is treated as self-service, and each download is audited. And a code is redeemed against this instance’s own MDM tenant, so it only works on the instance whose enrollment page it was typed into.

Install / Remove A Raw Profile

Below the curated catalog, two routes install or remove a configuration profile on one enrolled Mac directly. Install takes either a catalog profileKey (the control plane maps it to a locked .mobileconfig) or a raw profileBase64. Remove takes the profile’s payload identifier.

Guards: install returns 400 “udid required” without a udid; remove returns 400 unless both udid and identifier are present. Both return 400 when MDM is unconfigured; otherwise they follow the command outcome rules under Per-Device Commands (the MDM’s own status when it queued or refused the request, 424 when it did not answer or did not queue it). A raw profileBase64 is not bounded by the catalog, so it is refused with 403 unless the caller holds manage_device_destructive (or the administrator role), and the refusal is audited; a raw profile over 1,000,000 characters returns 413. Removing a profile is audited at warning level, because it strips an enforced control.

Configuration Profiles (Catalog, CRUD, Deploy)

A profile is a named bundle of payloads plus a scope (all devices / listed groups / listed devices). Payloads come from a fixed catalog with two engines. A profile belongs to one platform, and a scope can also carry exclusions — an excluded group or device is always out, whatever else matches. engine: 'mdm' payloads deploy as locked Apple profiles or MDM commands: screen_lock, mac_filevault, install_agent. engine: 'agent' payloads are applied by the target OS’s agent via the heartbeat. macOS: firewall, gatekeeper, software_updates, macos_major_updates, app_store_updates, disable_ssh, disable_screen_sharing, disable_guest, disable_autologin, agent_screen_lock. Linux: firewall, linux_auto_updates, auditd, time_sync, fail2ban. Windows: firewall, win_defender, win_auto_updates. On every platform, agent_update holds the scope on a chosen agent version and agent_freeze excludes it from agent auto-updates.

A profile change can reach its scope in stages (rings) rather than all at once. Devices the rollout has not reached keep the previous version — or get nothing, when the profile is new. To stage an edit to a live profile, send a rollout object with the edit on PUT /devices/profiles/:id; the edit and the rollout start are saved together, and 400 is returned if nothing changed. To stage a draft (not yet enabled) profile, use POST /devices/profiles/:id/rollout, which enables it for the first ring only. The rollout body is { rings[], autoPromote, promoteAfterHours }: 2–5 rings, each a set of groups or a percentage, the last always everyone. autoPromote defaults to true and promoteAfterHours to 24 (whole hours, 1–720, otherwise 400). A percentage ring is a whole number from 1 to 99, and each must be larger than the one before. With auto-promote on, the rollout moves to the next ring once the current ring has run for promoteAfterHours with no failed device; any failure in the ring holds it there until an admin promotes, pauses or rolls back. The check runs every 15 minutes. While a rollout is in progress the profile refuses further edits with 409 until it completes or is rolled back.

A second nuance worth knowing: within the catalog, some payloads are modelled but not yet live. win_bitlocker is live:false — it reports BitLocker state but does not enforce it (enforcement is pending recovery-key escrow). Deploy only acts on live payloads; a profile of non-live payloads returns "Nothing to deploy".

Smart Device Groups

Groups are the scope targets profiles point at. A static group has explicit member rows; a smart group computes membership from criteria against the inventory, re-evaluated on every read — so a smart group’s member count is worked out from each device’s last report, never from a cached snapshot.

Smart criteria are { match: 'all' | 'any', rules: [ { field, op, value } ] }. A smart group needs at least one valid rule. Only these fields are queryable. Inventory fields: platform, osVersion, modelName, status, agentVersion, serialNumber, name, hostname, osUpdateAvailable, department, location, costCenter, assetTag. Computed fields: owner (the assigned person’s name or email), diskFreePct, checkinDays (days since the last check-in), compliance (compliant or at_risk) and hasApp (an installed application). Operators: eq, neq, contains, startsWith, gt, gte, lt, lte, isTrue, isFalse. Some fields accept only a subset: diskFreePct and checkinDays take the four comparisons; compliance, department and location take eq / neq; hasApp takes contains / eq only — there is no “does not have app” rule, because it would sweep in every device that has not reported its software yet. Version fields compare as versions, so 14.10 is newer than 14.9.

Deleting a group that a profile or agent rollout is scoped to is refused with 409 and a usedBy list. Adding ?force=1 strips the group from those scopes first, then deletes it. A scope emptied that way targets nobody; it never widens to every device.

Phased Agent-Update Rollouts (Pilot Rings)

Adopting a new agent release with a scope creates a rollout — a testing ring — instead of moving the whole-OS baseline. scope: all (default) advances the fleet baseline for that OS; groups / devices leave the baseline untouched and offer the new version only to that ring. The list route reports, per ring, how many devices are in scope and how many already report the target version, so you can watch a ring land before widening.

The same two controls exist as profile payloads, so they can follow a scope instead of a single device: agent_update keeps a profile’s scope on a chosen agent version, and agent_freeze excludes the scope from agent auto-updates until the payload is removed.

Disk-Encryption Recovery Keys (FileVault / BitLocker)

This is the path that makes a locked-out FileVault or BitLocker machine recoverable — with a paper trail. The Windows agent escrows a BitLocker recovery key over its signed channel; a FileVault key is not sent by the Mac agent and arrives through Apple MDM instead. Either way the app stores it encrypted at rest (AES-256-GCM), never in plaintext and never in a list response. Revealing the plaintext is the only place decryption happens, and it sits behind the destructive gate: the manage_device_destructive permission, a step-up re-authentication, and a written reason, with a CRITICAL audit record written before the key is returned.

Rotating A FileVault Recovery Key (macOS Only)

A recovery key someone has read is no longer a secret, so your instance can replace it. Rotation applies to FileVault on Macs only — there is no BitLocker equivalent — and it is not instant: the Mac generates a new key at its next login by a FileVault user, and the new key is then escrowed through Apple MDM. It needs the current agent, FileVault on, and the FileVault profile installed on that Mac; otherwise the request is refused with 409 and the reason. Three things open a rotation: an admin asking for one, a reveal (on by default — the reveal response’s rotationScheduled says whether it did), and an optional schedule that replaces any key older than 30, 90, 180 or 365 days (off by default). Only one request is open per Mac at a time. Like the rest of FileVault escrow through Apple MDM, rotation is part of the preview and not yet validated end-to-end.

Who Can Do What