Manage Devices

Managing devices

This topic demonstrates how to use the device-management API functions (/Mobile) to perform an action on a mobile device. For example, you can do the following with these functions:

  • Enable or disable single sign-on (SSO) on a device.
  • Delete a device
  • Lock, unlock, power off, wipe, or reboot a device.
  • Ping a device.
  • Set a device as the primary device.
  • Manage policies for a device.
  • Manage containers and the client app on a device.

This topic assumes that the device is currently enrolled or was previously enrolled in Identity Platform, and that the user, on whose behalf you are invoking the device-management functions, has Device Management permissions.

Retrieving the device ID

Most of the /Mobile endpoints require the device identifier (deviceID) as an input parameter. You can run a query on the Device table to find the device ID. For example, if you need the device ID for all devices for a specific user, run a query that returns enough information to identify each device for a user who has enrolled multiple devices. You can select columns such as Name, DisplayModelName, and Model name, in addition to DeviceID and Owner and specify the owner using a Where clause with a query similar to the following:

/Redrock/Query
  {"Script":"
      Select Owner, deviceID, Name, DisplayModelName, ModelName from Device 
      where Owner = 'mikey@doccraft' ORDER BY deviceID COLLATE NOCASE"
  }

The query returns the specified columns, including deviceID, for the devices owned by mikey@doccraft. You can then pass the deviceID parameter to /Mobile functions to perform actions on any of these devices.

Device query sample response:

{
  "success": true,
  "Result": {
    "IsAggregate": false,
    "Count": 1,
    "Columns": [],
    "FullCount": 3,
    "Results": [
    {
      "Entities": [],
      "Row": {
        "Name": "SAMSUNG-SM-G900A (SN: R38F40F348K)",
        "Owner": "mikey@doccraft.com",
        "DeviceID": "fb6d74946c7f7994-R38F40F348K-1560043795",
        "DisplayModelName": "Samsung GALAXY S5",
        "ModelName": "SAMSUNG-SM-G900A"
      }
    },
    {
      "Entities": [],
      "Row": {
        "Name": "SAMSUNG-SM-N910V (PN: 4087096222)",
        "Owner": "mikey@doccraft",
        "DeviceID": "5ad3b8d5bca2e645-a2bad04b-1560043795",
        "DisplayModelName": "Samsung GALAXY Note 4",
        "ModelName": "SM-N910V"
      }
    },
    {
      "Entities": [],
      "Row": {
        "Name": "iPad",
        "Owner": "mikey@doccraft",
        "DeviceID": "aff19773cc277256732ba65398c6d4ed91c62504",
        "DisplayModelName": "iPad",
        "ModelName": "iPad"
      }
    }
    ],
    "ReturnID": ""
  },
  "Message": null,
  "MessageID": null,
  "Exception": null,
  "ErrorID": null,
  "ErrorCode": null,
  "InnerExceptions": null
}

Device management for a single device

Most of the device-management API functions perform a single action on a single device specified by the deviceID parameter, and can be used for any mobile device or Mac computer. For additional details about where a call is supported, see the [API reference].

The following examples show how the deviceID can be used:

  • Disable single sign-on (SSO) using /Mobile/DisableSSO on a device to prevent someone from logging into applications if the device has been lost or stolen:
/Mobile/DisableSSO
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Enable single sign-on (SSO) using /Mobile/EnableSSO after enrolling a new device or recovering a device on which you previously disabled SSO:
/Mobile/EnableSSO
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/PingDevice
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/DeleteDevice
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/WipeDevice
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/LockClientApp
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/LockDevice
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/PowerOff 
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/ReapplyDevicePolicy
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'} 
/Mobile/Reboot
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/RemoveDeviceProfile
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/ResetClientAppLockPin
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/SetPrimaryDevice
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/UnlockDevice
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
/Mobile/UpdateDevicePolicy 
   {'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Successful device-management call response. For a successful call, all of the preceding functions return "success: true" and null for everything else:
{
   "success": true,
   "Result": null,
   "Message": null,
   "MessageID": null,
   "Exception": null,
   "ErrorID": null,
   "ErrorCode": null,
   "InnerExceptions": null
}
  • Unsuccessful device-management call response. For an unsuccessful call, all of these functions return "success: false" and an error message such as: "Device 'deviceID' not found." for a device that Identity Platform can't find:
{
   "success": false,
   "Result": null,
   "Message": "Device 'fb6d74946c7f7994-R38F40F348K-1560043795' not found.",
   "MessageID": "_I18N_Centrify.Cloud.Core.Data.NotFoundException",
   "Exception": "Centrify.Cloud.Core.Data.NotFoundException: Device 'fb6d74946c7f7994-R38F40F348K-1560043795' not found.\r\n   at
      Centrify.Cloud.Mobile.Lib.Controllers.MobileController.<>c__DisplayClass2c.<enablesso>b__2b()\r\n   at
      Centrify.Cloud.Core.RestHelpers.JsonRest.StandardJsonResult(Action action)",
   "ErrorID": "4ab00c77-a582-4da8-90e5-f2b03c3325a9:c82f8922ac8945bb90cd29489b6334e2",
   "ErrorCode": null,
   "InnerExceptions": null
}

Most of the device management calls can be used for any mobile device or Mac computer. For additional details about where a call is supported, see the API reference.

See Also

Manage Devices


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.