Manage devices

This topic describes 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 CyberArk 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"
}

In this example, 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'}

Unenroll 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 CyberArk 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
}