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
}