Category filter

Streamline UEM Migration: How Hexnode Genie AI Automates Mac Disenrollment

TL;DR: Custom (Genie AI Discovery) automates public API research to disenroll Mac devices from your current UEM provider during macOS migration to Hexnode UEM. It automatically discovers Base URLs, auth protocols, and target endpoints to eliminate manual technical hurdles and prevent accidental device wipes. If public API documentation is unavailable, it seamlessly falls back to custom local script execution (.sh/.py) or manual API entry.

Executive Summary

Migrating macOS devices from legacy MDM, RMM, or patch management platforms to Hexnode often presents a significant “Knowledge Gap” for system administrators. Manually identifying vendor-specific API details is difficult, and entering the wrong command can accidentally wipe the device.

Hexnode Genie AI resolves this challenge by automatically researching your vendor’s public API documentation to map connection details, authentication protocols, and disenrollment endpoints. Built-in safety checks prevent accidental device wipes, while encrypted credential management and flexible fallbacks ensure a seamless transition to Hexnode UEM.

Key Capabilities

AI Discovery: Scans public documentation to pre-fill API structures, Base URLs, OAuth 2.0 Token URLs, and handshake sequences.
Safety Engine (“Zero-Wipe” Validation): Proactively detects destructive API payloads to prevent unintended factory resets during migration.
Flexible Fallbacks: Dynamically shifts to local shell script execution via the Hexnode Gateway agent or manual API input if cloud documentation cannot be fetched.
Privacy Shield: Sensitive API keys and tokens are encrypted at rest and never processed by the external AI engine.

How to configure disenrollment using Genie AI?

Login to your Hexnode UEM portal.
Navigate to Enroll > Platform Specific > macOS > Migrate to Hexnode.
Provide a name for the configuration file and Configure Gateway Settings.
Under Configure disenrollment settings, enable Remove device from existing MDM automatically.
From Specify the current MDM dropdown, select Custom (Genie AI Discovery) option.
Click the Bridge Discovery field or click the Configure Source Bridge with Genie to launch the setup wizard. There are two steps in the configuration:
1. Source Discovery
2. Technical Mapping
Search for your UEM provider name to locate its API documentation. Two scenarios may occur when searching for your UEM provider name:

Case 1: If public API documentation is found for your UEM provider

Step 1: Source Discovery

Genie AI scans public documentation to automatically retrieve the source UEM’s API schema—including the API Base URL, authentication protocols, and target disenrollment endpoints. Once the API schema is retrieved, click Review Configuration to proceed to Technical mapping.

Step 2: Technical Mapping

Configure the connection details based on the outcome of Source Discovery:
- Genie AI automatically pre-fills the API Base URL, Authentication Method, and Target API Endpoints (ID Lookup and Disenrollment commands).
- Review the populated fields, enter your tenant credentials (such as Client ID and Client Secret or API Tokens).
- If you want to edit the pre-filled details, click the Manual Auth Override option.
Case 2: If public API documentation is not found for your UEM provider:

Step 1: Source Discovery

Select one of the following options to determine how disenrollment will be handled:
- Try another search: Enter the exact vendor’s name again in the search bar (if the initial attempt had a typo) or search using an alternative vendor name.
- Upload Local Shell Script: Select this option to upload your custom disenrollment script (.sh or .py) for local execution via the Hexnode Gateway agent.
- Manual API Entry: Select this option to manually enter your current UEM’s API connection details and endpoints.
Step 2: Technical Mapping
- If Upload Local Shell Script is selected: Upload your validated custom disenrollment script (.sh or .py). The script is bundled with the Hexnode Gateway agent for local execution on target Mac endpoints.
  After uploading the script, verify or modify the Binary path and enter any Arguments required to execute your script.
- If Manual API Entry is selected: Manually define the custom handshake logic by entering the API Base URL, Authentication Method, Credentials, and Target API Endpoints (ID Lookup and Disenrollment commands).

Manual API Entry Fields

Section	Field	Description
API Setup	API Base URL	The main server address (URL) used to access your current UEM’s API. Enter the root tenant domain URL of your current UEM. Example: `https://your-instance.jamfcloud.com/api`
Authentication	Authentication Method	The protocol used to authenticate API requests. Select the authentication protocol required by your source UEM. The available options are: OAuth 2.0 API Key Basic Auth Custom Header
	OAuth 2.0 Type (available when Authentication Method is OAuth 2.0)	Specifies the authorization flow type. Select OAuth 2.0 (Bearer token) or OAuth 2.0 (Client ID + Secret) based on your source UEM API settings.
	Token Exchange URL (available when OAuth 2.0 Type is OAuth 2.0 (Client ID + Secret))	The API endpoint path used to exchange the Client ID and Client Secret for a temporary OAuth 2.0 access token. Enter the token request endpoint route provided by your source UEM. Example: `/v1/auth/token` or `/oauth/v2/token`
Credentials	Bearer Token (available when Authentication Method is OAuth 2.0 (Bearer token))	The secret token generated by the source UEM used to authorize API requests. Generate an access token in your source UEM portal and paste the secret token string here.
	Client ID (available when OAuth 2.0 Type is OAuth 2.0 (Client ID + Secret))	The public application identifier assigned to your API client by the source UEM. Enter the Client ID generated from your source UEM’s API or integration console.
	Client Secret (available when OAuth 2.0 Type is OAuth 2.0 (Client ID + Secret))	The confidential secret key associated with the Client ID used to authenticate token requests. Copy and paste the Client Secret generated alongside the Client ID in your source UEM portal.
	Header Name (available when Authentication Method is API Key)	The HTTP header key name used to pass the API key. Specify the exact HTTP header key name expected by your source UEM. Example: `x-api-key` or `Authorization`
	API Key (available when Authentication Method is API Key)	The unique API key credential required for authentication. Enter the active API key generated from your source UEM admin console.
	Username (available when Authentication Method is Basic Auth)	The admin account username required for Basic HTTP authentication. Enter the username of the dedicated service account or admin account configured for API access.
	Password (available when Authentication Method is Basic Auth)	The password or token corresponding to the Basic Auth username. Enter the account password or API token associated with the Basic Auth account.
	Header Name (available when Authentication Method is Custom Header)	The custom HTTP header key name required by the source UEM API. Enter the custom authorization header key required by your source UEM.
	Header Value (available when Authentication Method is Custom Header)	The corresponding header value or secret string passed for custom authorization. Enter the secret token or authorization value paired with the custom header key.
Target API Endpoints	Type	Select the device identification method: Direct Serial: Targets the device directly by serial number. ID Lookup: Queries the API for an internal device ID before disenrollment.
Target ID Lookup	Endpoint	The API path used to query and locate the target device’s internal ID in the source UEM. Enter the API endpoint route used to query device IDs. Example: `/v2/mobile-devices?filter=serialNumber%3D%3D"{serialNumber}"`
	Method	The HTTP method executed for the ID lookup request. Select the required HTTP method (GET, POST, PUT, PATCH, DELETE).
	Headers	Additional HTTP headers required for the ID lookup call. Define any mandatory request headers required by the source API. Example: `{"Accept": "application/json"}`
	Request Body	Payload data sent alongside the ID lookup API request. Enter the required request payload structure if querying device IDs via POST or PUT.
Final Disenrollment Command	Endpoint	The specific API route executed to send the remote unmanage/disenrollment command. Enter the exact API route path that triggers device removal. Example: `/v1/mobile-device-commands/unmanage-device`
	Method	The HTTP method used to invoke the disenrollment command. Select the required HTTP method (POST, GET, PUT, PATCH, DELETE).
	Headers	Additional HTTP headers required for the disenrollment call. Specify any operational headers needed for command authorization. Example: `{"Content-Type": "application/json"}`
	Request Body	Payload data sent to execute the disenrollment request. Supply the JSON payload string required by the source UEM to execute device removal.

8. Click Confirm to save the Custom (Genie AI Discovery) configuration.

Troubleshooting

Local script execution fails on target Mac endpoints
- Cause: Incorrect binary interpreter path or missing command arguments.
- Resolution: Under Technical Mapping, verify that the Binary path matches the interpreter on the target Mac (/bin/bash for Bash, or /usr/bin/python3 for Python). Ensure all required parameters are entered in the Arguments field as space-separated values.
Target device disenrollment command fails during migration execution
- Cause: The internal device ID lookup failed to map the Mac’s serial number, or the disenrollment API endpoint route is invalid.
- Resolution: Under Technical Mapping in the Hexnode UEM Portal, inspect Target API Endpoints. Ensure the Target ID Lookup route correctly includes the dynamic parameter (e.g., {serialNumber}), and verify that the Final Disenrollment Command endpoint path and HTTP method match your source UEM’s API specification.

Frequently Asked Questions

Does Hexnode Genie AI access or store source UEM API credentials?

No. All sensitive credentials—such as Client Secrets, API Keys, and Bearer Tokens—are encrypted at rest within your Hexnode UEM tenant and are never processed by or passed to the external AI engine.

Will automatic disenrollment trigger a factory reset or wipe data on target Macs?

No. Genie AI incorporates a Safety Engine (“Zero-Wipe” Validation) that proactively checks disenrollment payloads to prevent destructive commands or factory resets, ensuring devices are unmanaged without user data loss.

What permissions are required for the source UEM API key or service account?

The API key or service account configured in the source UEM only requires read permissions for device inventory lookup and execute permissions for device disenrollment/unmanage commands. Full administrative privileges are not required.