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 }