Manage 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 the Identity platform, and that the user, on whose behalf you are invoking the device-management functions, has Device Management permissions.

Retrieve 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 ModelName, 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
	}
}

Manage 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 you can use the deviceID :

  • Disable single sign-on (SSO) using /Mobile/DisableSSO on a device to prevent someone from logging in to applications if the device is 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'}
  • Ping a device using /Mobile/PingDevice to see if it is reachable:

    /Mobile/PingDevice
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Remove a device from CyberArk Identity using /Mobile/DeleteDevice:

    /Mobile/DeleteDevice
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Wipe a device that has been lost or stolen using /Mobile/WipeDevice:

    /Mobile/WipeDevice
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Lock a mobile client application using /Mobile/LockClientApp:

    /Mobile/LockClientApp
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Lock a mobile device screen using /Mobile/LockDevice:

    /Mobile/LockDevice
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Power off a device using /Mobile/PowerOff:

    /Mobile/PowerOff 
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Reapply device policies using /Mobile/ReapplyDevicePolicy :

    /Mobile/ReapplyDevicePolicy
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Reboot a device using /Mobile/Reboot:

    /Mobile/Reboot
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Un-enroll a device from CyberArk Identity using /Mobile/RemoveDeviceProfile:

    /Mobile/RemoveDeviceProfile
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Reset the personal identification code used to unlock the device using /Mobile/ResetClientAppLockPin:

    /Mobile/ResetClientAppLockPin
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Set a device as the primary device using /Mobile/SetPrimaryDevice:

    /Mobile/SetPrimaryDevice
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Unlock a device using /Mobile/UnlockDevice:

    /Mobile/UnlockDevice
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}
  • Update device policies using /Mobile/UpdateDevicePolicy :

    /Mobile/UpdateDevicePolicy 
    	{'deviceID': 'fb6d74946c7f7994-R38F40F348K-1560043795'}

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.

Device management responses

  • 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
    }
  • For an unsuccessful call, all of the preceding functions return "success: false" and an error message such as: "Device 'deviceID' not found" for a device that the Identity platform can't find:

    {
    	"success": false,
    	"Result": null,
    	"Message": "Device 'fb6d74946c7f7994-R38F40F348K-1560043795' not found.",
    	"MessageID": "_I18N_Idaptive.Cloud.Core.Data.NotFoundException",
    	"Exception": "Idaptive.Cloud.Core.Data.NotFoundException: Device 'fb6d74946c7f7994-R38F40F348K-1560043795' not found.\r\n   at
    		Idaptive.Cloud.Mobile.Lib.Controllers.MobileController.<>c__DisplayClass2c.<enablesso>b__2b()\r\n   at
    		Idaptive.Cloud.Core.RestHelpers.JsonRest.StandardJsonResult(Action action)",
    	"ErrorID": "4ab00c77-a582-4da8-90e5-f2b03c3325a9:c82f8922ac8945bb90cd29489b6334e2",
    	"ErrorCode": null,
    	"InnerExceptions": null
    }