Using the New Lost Mode API on iOS Devices in Workspace ONE UEM

With more companies supporting a hybrid workforce, the risk of lost devices has become a growing security concern. End users are carrying increasingly more corporate data on their mobile devices than ever before. Each day, these power users are losing their devices in airports, taxis, rental cars, and hotels, just to name a few of the locations where devices are vulnerable. Each device lost brings with it significant risk for the company, especially if the device ends up in the wrong hands.

In a 2009 study sponsored by Intel and conducted by the Ponemon Institute, it was estimated that a single lost laptop can cost a company, on average, $49,246. This figure includes the cost of device replacement, forensics, potential data breaches, lost intellectual property, legal fees, and consulting and regulatory expenses. Although not included in the study, it is safe to assume, as mobile devices supplant laptops as an end user’s on-the-go device, that this cost can be applied to those devices as well.

As iOS devices, such as iPhones and iPads, continue to proliferate into the enterprise space, IT admins must ensure they can take quick action to lock down lost mobile devices as soon as possible to mitigate data loss and breaches. Workspace ONE UEM already includes an Enable Lost Mode feature for iOS devices that allows IT admins to enable iOS Lost Mode on a device and customize a message on the lock screen. You can find the Enable Lost Mode button on the device’s Details View under the More Actions menu.

Selecting the button prompts IT admins to enter a message to be displayed on the device lock screen, as well as a phone number and a footnote to be displayed as well. 

This option works well for most organizations, but what if you want to enable or deactivate Lost Mode programmatically on an iOS device, or through another tool?

Lost Mode API

With the release of version 2402 of Workspace ONE UEM, we have introduced a new Lost Mode API, which allows IT admins to issue a command to enable or deactivate Lost Mode using the Workspace ONE UEM REST API. This gives organizations the ability to issue the Lost Mode command programmatically from, for instance, a third-party help desk ticketing platform that can send REST API commands to external systems.

If you’ve never used the Workspace ONE UEM REST API before, I’d suggest that you start by reviewing the Workspace ONE UEM product docs. You might also wish to check out this recent article on Tech Zone about using the new API Postman collection.

The new Lost Mode API allows IT admins to set the same properties as the UI (message, phone number, and footnote). The following table describes the parameters required for the Lost Mode API.

Making a Lost Mode API Call to the Workspace ONE UEM REST API

There are a few things you will need prior to sending the REST API call. You can find each of these items either in the Workspace ONE UEM console or the Workspace ONE UEM REST API documentation.

• REST API URL Endpoint – This is the URL for the specific API command you wish to call. It consists of the API site URL, the API subsystem, and the specific API endpoint you want to use. For example, an API endpoint URL might look like: https://as1234.awmdm.com/API/mdm/devices.
• Tenant Code – This is the code for your Workspace ONE UEM tenant. See the blog post listed above for details on where to find this information.
• REST API Login Credentials – You will always require credentials to make REST API calls. There are three authentication types accepted by the REST API: Basic, OAuth, and Certificate. For this example, we will use basic authentication with a Base64 encoded username and password. See the above-mentioned blog post for more information on how to create a Base64 encoded username and password.
• Response Context – This will determine the format of the data that Workspace ONE will return in response to your API call. In this example, we will use application/json;version=2.
• Unique Device ID (Uuid) – This is the unique identifier that Workspace ONE uses to identify the target device from all the others in the console.
• REST API Client – Although you can make API calls from the Workspace ONE UEM REST API documentation, you will most likely want to use a client specifically designed to make REST API calls. If you are looking to integrate the Enable Lost Mode functionality into a third-party helpdesk application that supports REST API calls, you should consult that application’s documentation on how to make REST API calls from the app. For this post, I will be using Postman to make the API call.

In Postman, you will start by creating the Request URL. This is composed of the REST API URL Endpoint, the unique device ID, the specific API (in this case, lostmode), and the value of enableLostMode parameter. For example, the Request URL might look like: https://as1234.awmdm.com/API/mdm/devices/1a234b67-890c-1234-d567-890e123fg456/lostmode/true. Enter that URL in the Request URL field and use the dropdown to change the REST method to Put.

Now you need to add some headers that will provide additional required information to the REST API when you make the call, such as REST API login credentials, tenant code, and response context. In Postman, select the Headers tab and begin to create your keys. The keys required are:

When finished, your headers should look similar to this.

Finally, you need to add the body of the API call to Postman. The body contains the three properties discussed earlier: footnote, message, and phone_number. Keep in mind that you must include, at a minimum, either message or phone_number. Click the Body tab and select raw. Enter the body in the field provided.

Now, you should be ready to send the REST API call to place the device in Lost Mode. Click the Send button.

The above example call would enable Lost Mode on the target device. However, if you want to deactivate Lost Mode once the device has been found, you simply need to change the true to false in the Request URL and resend the command. For example, the Request URL to deactivate Lost Mode might look like this: https://as1234.awmdm.com/API/mdm/devices/1a234b67-890c-1234-d567-890e123fg456/lostmode/false.

If Workspace ONE UEM receives the command successfully, the REST API will return a HTTP Status Code of 202.

Example Use Cases for the Lost Mode API

With a button in Workspace ONE UEM that can enable and deactivate Lost Mode on individual devices, you might be questioning why someone would want to use the REST API. Here are a few examples.

• When a user calls the help desk to report a lost iOS device, you might want to allow your help desk team to enable Lost Mode on the device from within your help desk ticketing system without having to log into the Workspace ONE console. There are a few prerequisites for this to work, such as your ticketing application being able to send REST API calls, and some customization required within the application to add a mechanism, such as a button, to trigger the API call. Your ticketing system would also need a way to correlate device unique identifiers with the user assignment. 
• You can use the REST API to provide your end users with the ability to enable Lost Mode in a self-service fashion. For instance, if an end user realizes that they’ve lost their iOS device, they could connect to a website from another device and simply click a button that would trigger the Lost Mode API call. Like the previous example, this would require a mechanism to correlate the user with a device unique identifier. 

Summary

The new Lost Mode API in Workspace ONE UEM is an excellent option for IT admins who need to programmatically enable or deactivate Lost Mode on iOS devices. This new feature uses the Workspace ONE UEM REST API and allows IT admins to configure the same parameters for Lost Mode that they can in the console. This new feature is ideal for organizations that want to simplify management with automation and integration.

To learn more about managing iOS devices with Workspace ONE, check out these EUC Tech Zone resources.