# Workspace ONE

Connect Omnissa Workspace ONE UEM to Risotto so the support agent can look up a requestor's devices, get BitLocker recovery keys, and restart or wipe devices

The Workspace ONE integration lets Risotto read the devices that are enrolled to a user in Omnissa Workspace ONE UEM. With the **Workspace ONE Get Device Information** tool, the support agent can find a requestor's device and its details while it works a ticket. With the **Workspace ONE Get BitLocker Recovery Key** tool, the agent can give a requester the BitLocker recovery key of their Windows device. With the **Workspace ONE Restart Device** and **Workspace ONE Wipe Device** tools, the agent can restart a device or erase a Windows device.

> **Note:** The Workspace ONE integration supports Workspace ONE UEM SaaS tenants only.

## Prerequisites

- **Admin access to the Workspace ONE UEM console**, to create an OAuth client
- A Workspace ONE UEM SaaS tenant whose REST API host looks like `as1234.awmdm.com`
- **The Org Admin or Manager role in Risotto**

## Setup

1. **Find your REST API host**

   In the UEM console, go to **Groups & Settings > All Settings > System > Advanced > API > REST API**. Copy the host of the **REST API URL**, for example `as1234.awmdm.com`.

2. **Create an OAuth client**

   Go to **Groups & Settings > Configurations > OAuth Client Management** and click **Add**.

   Name the client "Risotto" and select your Customer organization group. Select a role that can read devices. A dedicated REST API admin role is the safest choice. To use the BitLocker recovery key tool, the role must also be able to read BitLocker recovery keys. To use the restart or wipe tool, the role must also be able to send device commands. Keep the status **Enabled** and click **Save**.

   Copy the **Client ID** and the **Client Secret**. The console shows the secret only once.

3. **Open the Workspace ONE integration in Risotto**

   In the dashboard, go to **Settings > Integrations** and click the **Workspace ONE** card. On the **API client** card, click **Connect**.

   *Product example: Workspace ONE's integration page in Settings, not connected, with Connect on the API client card ringed.*

4. **Enter the OAuth client details**

   In the **Workspace ONE** dialog, fill in these fields, then click **Save**:

   | Field             | Description                                                                                                                                                                          |
   | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
   | **API Host**      | Your REST API host, for example `as1234.awmdm.com`. You can paste the full URL.                                                                                                      |
   | **Region**        | The data center of your tenant: **North America (US, Canada)**, **Europe (UK, Germany)**, **Asia Pacific (India, Japan, Singapore, Australia, Hong Kong)**, or **UAT environments**. |
   | **Client ID**     | The client ID of the OAuth client.                                                                                                                                                   |
   | **Client Secret** | The client secret of the OAuth client.                                                                                                                                               |

   *Product example: The Workspace ONE setup dialog filled in with Northwind's API host, the North America region, a client ID and secret, with Save ringed.*

   Risotto tests the connection before it saves. If the test fails, nothing is saved and the dialog shows the error. When it succeeds, Risotto shows "Workspace ONE settings saved", and the **API client** card shows **Connected** with your API host, region and client ID.

5. **Enable the tool**

   Select **Tools** in the sidebar, find **Workspace ONE Get Device Information**, and enable it. A new tool is named **Get Workspace ONE Device Details**. To try it, open the tool, click **Run tool**, and run it in the dialog. With **Restrict to Requestor Only** on, the run looks up your own devices.

## Workspace ONE Get Device Information

The tool lists the devices enrolled to a user, with the name, model, OS, serial number, last seen time, and compliance status of each. For one device, it also returns the enrollment status, ownership, enrollment user, organization group, and device ID. When the user has more than one device, the agent asks which one by name and model, then gets the details of that device.

- **email_address** (optional): the user to look up. The default is the ticket requestor.
- **device_id** (optional): one device of that user.
- **Restrict to Requestor Only** (default: on): the tool returns only the devices of the ticket requestor. Turn it off to let your team look up other users' devices.

The tool only reads. It does not change a device.

## Workspace ONE Get BitLocker Recovery Key

The tool gets the BitLocker recovery key of the requester's Windows device. Enable it on the **Tools** page. A new tool is named **Get BitLocker Recovery Key**.

- The tool reads only Windows devices. It skips phones, tablets, and Macs.
- If the requester has more than one Windows device, the agent asks which one, by name and model.
- Without a Key ID, the tool returns the key of the operating system drive.
- **key_id** (optional): the Key ID that the BitLocker recovery screen shows. The first 8 characters are enough. Case and braces do not matter. The tool returns the key of the drive with that Key ID.
- **email_address** and **device_id** (optional): the same as in the device information tool.

Tool options:

- **Restrict to Requestor Only** (default: on): the tool returns keys only for the devices of the ticket requester.
- **Send via DM Only** (default: on): Risotto sends the key to the requester in a direct message (Slack or Microsoft Teams), not in the ticket thread. If Risotto cannot send the direct message, it does not post the key. The tool fails, and the agent escalates the ticket. A tool that was saved with this option off keeps posting the key in the ticket thread until you turn the option on.

> **Warning:** Give the role of the OAuth client the BitLocker permissions in Workspace ONE
> UEM. Without them, the tool fails with "Workspace ONE refused the BitLocker
> request", even though device lookups work.

## Workspace ONE Restart Device

The tool restarts a device of the requester. Enable it on the **Tools** page. A new tool is named **Restart Device**, and **Requires Approval** is on by default.

- The tool works on all platforms: Windows, macOS, phones, and tablets.
- If the requester has more than one device, the agent asks which one, by name and model.
- **email_address** and **device_id** (optional): the same as in the device information tool.
- Workspace ONE queues the restart. The device restarts the next time it checks in, usually within a few minutes if it is on and online. The agent tells the requester that the restart is queued, not that it is done.
- The requester loses unsaved work on the device.

Tool option:

- **Restrict to Requestor Only** (default: on): the tool restarts only the devices of the ticket requester.

## Workspace ONE Wipe Device

The tool erases all data on a Windows device and resets the device to factory settings. You cannot undo a wipe. Enable the tool on the **Tools** page. A new tool is named **Wipe Device**, and **Requires Approval** is on by default. Keep approval on, so that a person accepts each wipe before it runs.

- The tool wipes only Windows devices. It refuses macOS devices, phones, and tablets.
- The tool sends a full wipe. It does not send an Enterprise Wipe.
- The agent first finds the device with the device information tool. Then it sends **device_id**, **device_name**, **model**, and **serial_number** (all required). The approver sees these values.
- After approval, Risotto compares the name, model, and serial number with the device in Workspace ONE. If one value does not match, Risotto wipes nothing.
- **email_address** (optional): the same as in the device information tool.
- Workspace ONE queues the wipe. The device erases its data the next time it checks in.

Tool option:

- **Restrict to Requestor Only** (default: on): the tool wipes only the devices of the ticket requester.

> **Warning:** Give the role of the OAuth client the device command permissions in Workspace
> ONE UEM. Without them, the restart and wipe tools fail with "Workspace ONE
> refused the restart command" or "Workspace ONE refused the wipe command", even
> though device lookups work.

## More than one device management platform

You can connect Workspace ONE together with Jamf Pro, Microsoft Intune, Iru (formerly Kandji), or Fleet. The support agent and the Assistant look up a requester's devices in every connected platform, in this order: Jamf Pro, Microsoft Intune, Iru (formerly Kandji), Workspace ONE, then [Fleet](https://www.tryrisotto.com/docs/integrations/device-management/fleet). They show the devices of all platforms together, each with the platform that reported it. If one platform does not respond, the agent still gets the devices from the others. A device that is enrolled in two platforms shows once for each platform.

## Troubleshooting

### Workspace ONE API host must be your tenant's REST API server

Risotto accepts only a SaaS REST API host such as `as1234.awmdm.com` (also on `awmdm.co.uk`, `awmdm.jp`, `awmdm.sg`, or `airwatchportals.com`). Copy the host from **Groups & Settings > All Settings > System > Advanced > API > REST API**. A dedicated tenant on another domain is not supported yet.

### Workspace ONE refused the OAuth client ID or secret

Check the client ID and secret. Check that **Region** matches the data center of your tenant.

### Workspace ONE accepted the OAuth client but refused the API call

Check that **API Host** is correct and that the role of the OAuth client can use the REST API.

### Workspace ONE could not be reached

Check **API Host** and try again.

Source: https://www.tryrisotto.com/docs/integrations/device-management/workspace-one
