> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Omnissa Workspace ONE UEM

> Connect Omnissa Workspace ONE UEM (formerly VMware Workspace ONE / AirWatch) to Serval to search enrolled devices, look up enrollment users, send device commands, and manage tags and smart groups from Serval workflows.

## About Omnissa Workspace ONE UEM

Omnissa Workspace ONE UEM is a unified endpoint management (UEM) platform for iOS, Android, macOS, Windows, Linux, and rugged devices. Connecting it to Serval lets your team search device inventory, look up which devices belong to a user, send device commands such as lock or enterprise wipe, and manage tags, smart groups, and organization groups—all through Serval workflows that call the Workspace ONE UEM REST API on your behalf. Serval only ever sends authenticated requests to the exact API host you configure.

**Authentication:** OAuth 2.0 client credentials. You create an OAuth client in the UEM console and give Serval the client ID, client secret, your tenant's REST API host, and the Omnissa token-service region. Serval stores the client ID and an encrypted copy of the secret, exchanges them for short-lived bearer tokens against Omnissa's token service, and refreshes tokens automatically. No API key (`aw-tenant-code`) is needed.

**Data sync:** On demand. Workflows call the UEM APIs when they run, subject to each workflow's approval procedure. There's no background sync or webhook.

## What the integration enables

| Capability                          | Description                                                                                                                                                                                                                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Device inventory                    | Search enrolled devices by user, platform, model, ownership, compliance status, or last-seen date; look up a single device by serial number, UDID, MAC address, or IMEI; and read installed apps.                                                                                          |
| Device commands                     | Send UEM commands to a device. The prebuilt workflow offers the non-destructive set (lock, query, sync, clear passcode, soft reset, shutdown); enterprise wipe and device wipe remain available to custom workflows through the API action, where you set the approval procedure yourself. |
| Users and groups                    | Search enrollment users, read organization groups, read smart groups and their members, and add or remove device tags.                                                                                                                                                                     |
| Applications                        | Search internal, public, and purchased apps and check their install status on devices.                                                                                                                                                                                                     |
| Full API access in custom workflows | Custom Serval workflows can call any endpoint in the MDM, System, MAM, MCM, and MEM API groups across API versions 1 through 4, with typed request and response schemas.                                                                                                                   |
| Connection health checks            | Four built-in checks exercise tenant info, device search, user search, and smart groups, so a missing admin-role permission shows up as exactly one failing check.                                                                                                                         |

Anything documented on your tenant's API help page (`https://<your-api-host>/api/help`) or in the [Workspace ONE UEM API reference](https://developer.omnissa.com/workspace-one-uem-apis/) can be accessed through Serval.

## Get your credentials

You need four things from Workspace ONE UEM: the **REST API host**, the **token region**, and an OAuth **client ID** and **client secret**. Omnissa's guide is [Using UEM Functionality With a REST API](https://docs.omnissa.com/bundle/WorkspaceONE-UEM-Console-BasicsVSaaS/page/UsingUEMFunctionalityWithRESTAPI.html).

<Steps>
  <Step title="Find your REST API host">
    In the UEM console, switch to your Customer organization group (or below) and go to **Groups & Settings** > **All Settings** > **System** > **Advanced** > **API** > **REST API**. The **REST API URL** looks like `https://as1234.awmdm.com/API`. The host is the part before `/API`, for example `as1234.awmdm.com`. On-premises tenants use their own hostname.

    <Note>
      Ignore the **API Key** on this page. Serval authenticates with an OAuth client, which doesn't need the `aw-tenant-code` key.
    </Note>
  </Step>

  <Step title="Determine your token region">
    Omnissa mints OAuth tokens from a regional token service, separate from your API host. Look up your data center in Omnissa's **Datacenter and Token URLs** table (linked from the guide above) and note the region: **North America**, **EMEA**, **Asia Pacific**, or **UAT** for pre-production tenants. The token URLs are `https://na.uemauth.workspaceone.com/connect/token`, `https://emea.uemauth.workspaceone.com/connect/token`, `https://apac.uemauth.workspaceone.com/connect/token`, and `https://uat.uemauth.workspaceone.com/connect/token`.

    <Tip>
      Older documentation lists the same regions on `uemauth.vmwservices.com`. Omnissa is retiring those hosts; Serval uses the `workspaceone.com` hosts.
    </Tip>
  </Step>

  <Step title="Create an admin role for Serval (recommended)">
    Go to **Accounts** > **Administrators** > **Roles** and create a role that grants only the REST API permissions Serval needs—at minimum the read permissions for devices, users, and smart groups covered by the health checks, plus any device-command or tag permissions your workflows use. You can widen the role later without reconnecting.
  </Step>

  <Step title="Create the OAuth client">
    Go to **Groups & Settings** > **Configurations** > **OAuth Client Management** and click **Add**. Name the client (for example, "Serval"), pick the organization group it should operate in, assign the role from the previous step, set the status to **Enabled**, and save.
  </Step>

  <Step title="Copy the client ID and secret">
    Copy both values immediately and store them securely.

    <Warning>
      Workspace ONE UEM shows the client secret only once. If you lose it, create a new OAuth client.
    </Warning>
  </Step>
</Steps>

## Connect in Serval

<Steps>
  <Step title="Open the Workspace ONE UEM connection form">
    In Serval, open **Integrations**, find **Omnissa Workspace ONE UEM** on the **All integrations** tab, and start a new connection.
  </Step>

  <Step title="Enter the API Host (required)">
    Enter your tenant's REST API host, for example `as1234.awmdm.com`, without `https://`, a path, or a port. The form rejects anything else with: "Enter a hostname such as as1234.awmdm.com (no https\://, path, or port)".
  </Step>

  <Step title="Select the Token Region (required)">
    Choose **North America**, **EMEA**, **Asia Pacific**, or **UAT / pre-production** to match your data center.
  </Step>

  <Step title="Enter the Client ID and Client Secret (required)">
    Paste the OAuth client's ID and secret.
  </Step>

  <Step title="Save the connection">
    Save, then verify the connection using the health checks below.
  </Step>
</Steps>

<Note>
  **When editing an existing connection:** the stored client secret is shown obfuscated, so paste the full secret again to change it. Leaving **API Host** or **Token Region** unchanged keeps the saved values.
</Note>

Serval pins the bearer token to the exact API host you configured. A workflow request to any other host—including another tenant's `awmdm.com` host—receives no credentials.

## Verifying the connection

The integration ships four health checks:

1. **Test Workspace ONE UEM Connection**: obtains a token and reads tenant info. Success: "Successfully authenticated with Workspace ONE UEM at \[your API host] (version \[UEM version])".
2. **List Workspace ONE UEM Devices**: searches devices with a page size of one and reports the enrolled total.
3. **List Workspace ONE UEM Enrollment Users**: searches enrollment users with a page size of one.
4. **List Workspace ONE UEM Smart Groups**: lists smart groups with a page size of one.

Each failure starts with "Unable to ..." followed by a specific reason. A `401` adds "Workspace ONE UEM rejected the OAuth client credentials. Verify the Client ID, Client Secret, and token region in the integration settings." A `403` adds "The OAuth client's admin role does not grant this permission."

<Tip>
  If the connection check passes but one of the other checks fails, authentication works and the OAuth client's admin role is missing that one resource permission. Fix it in **Accounts** > **Administrators** > **Roles**.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Authentication fails even though the client ID and secret are correct">
    The most common cause is a token region that doesn't match your data center: the token service returns `401` for clients it doesn't know about. Confirm the region against Omnissa's Datacenter and Token URLs table and edit the connection. Also confirm the OAuth client's status is **Enabled** in the UEM console.
  </Accordion>

  <Accordion title="Requests return 403 for one resource while others work">
    Workspace ONE UEM authorizes each REST endpoint through the admin role assigned to the OAuth client. A `403` means the role lacks that resource's permission, not that the credentials are wrong. Add the permission to the role; no reconnect is needed.
  </Accordion>

  <Accordion title="Results only include some of my devices">
    The OAuth client operates in the organization group you chose when creating it and sees devices in that group and its children. Create the client at your Customer organization group to see the whole tenant, or pass `lgid` in device searches to target a specific group.
  </Accordion>

  <Accordion title="A device search returns at most 500 devices">
    UEM search endpoints are paged with `page` (starting at 0) and `pagesize` (maximum 500) and return a `Total`. Custom workflows should keep requesting pages until `page * pagesize` reaches `Total`.
  </Accordion>

  <Accordion title="The same path returns different fields than the API help page shows">
    Workspace ONE UEM selects the API version from the `Accept` header, and the same path can exist in several versions. Serval exposes one action per version: `apiRequest` sends version 1, and `apiRequestV2`, `apiRequestV3`, and `apiRequestV4` send the newer versions. Use the action matching the version tab on the API help page.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Omnissa Workspace ONE UEM integration.