GuidesAPI ReferenceGitHub
Guides
Community ForumsTwitter

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": "[email protected]",
        "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

Updated about 5 years ago