Method: enterprises.devices.issueCommand

Issues a command to a device. The Operation resource returned contains a Command in its metadata field. Use the get operation method to get the status of the command.

HTTP request

POST https://androidmanagement.googleapis.com/v1/{name=enterprises/*/devices/*}:issueCommand

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

The name of the device in the form enterprises/{enterpriseId}/devices/{deviceId}.

Request body

The request body contains an instance of Command.

Response body

If successful, the response body contains an instance of Operation.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/androidmanagement

For more information, see the OAuth 2.0 Overview.

Command

A command.

JSON representation
{
  "type": enum (CommandType),
  "createTime": string,
  "duration": string,
  "userName": string,
  "errorCode": enum (CommandErrorCode),
  "newPassword": string,
  "resetPasswordFlags": [
    enum (ResetPasswordFlag)
  ],

  // Union field params can be only one of the following:
  "clearAppsDataParams": {
    object (ClearAppsDataParams)
  },
  "startLostModeParams": {
    object (StartLostModeParams)
  },
  "stopLostModeParams": {
    object (StopLostModeParams)
  }
  // End of list of possible types for union field params.

  // Union field status can be only one of the following:
  "clearAppsDataStatus": {
    object (ClearAppsDataStatus)
  },
  "startLostModeStatus": {
    object (StartLostModeStatus)
  },
  "stopLostModeStatus": {
    object (StopLostModeStatus)
  }
  // End of list of possible types for union field status.
}
Fields
type

enum (CommandType)

The type of the command.

createTime

string (Timestamp format)

The timestamp at which the command was created. The timestamp is automatically generated by the server.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

duration

string (Duration format)

The duration for which the command is valid. The command will expire if not executed by the device during this time. The default duration if unspecified is ten minutes. There is no maximum duration.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".

userName

string

The resource name of the user that owns the device in the form enterprises/{enterpriseId}/users/{userId}. This is automatically generated by the server based on the device the command is sent to.

errorCode

enum (CommandErrorCode)

If the command failed, an error code explaining the failure. This is not set when the command is cancelled by the caller.

newPassword

string

For commands of type RESET_PASSWORD, optionally specifies the new password. Note: The new password must be at least 6 characters long if it is numeric in case of Android 14 devices. Else the command will fail with INVALID_VALUE.

resetPasswordFlags[]

enum (ResetPasswordFlag)

For commands of type RESET_PASSWORD, optionally specifies flags.

Union field params. Parameters specific to the command. Note that some commands do not use this, in particular LOCK, RESET_PASSWORD, REBOOT, and RELINQUISH_OWNERSHIP. In future these commands may use this as well.

If this is set, then the fields new_password and reset_password_flags must not be set. params can be only one of the following:

clearAppsDataParams

object (ClearAppsDataParams)

Parameters for the CLEAR_APP_DATA command to clear the data of specified apps from the device. See ClearAppsDataParams. If this is set, then it is suggested that type should not be set. In this case, the server automatically sets it to CLEAR_APP_DATA. It is also acceptable to explicitly set type to CLEAR_APP_DATA.

startLostModeParams

object (StartLostModeParams)

Parameters for the START_LOST_MODE command to put the device into lost mode. See StartLostModeParams. If this is set, then it is suggested that type should not be set. In this case, the server automatically sets it to START_LOST_MODE. It is also acceptable to explicitly set type to START_LOST_MODE.

stopLostModeParams

object (StopLostModeParams)

Parameters for the STOP_LOST_MODE command to take the device out of lost mode. See StopLostModeParams. If this is set, then it is suggested that type should not be set. In this case, the server automatically sets it to STOP_LOST_MODE. It is also acceptable to explicitly set type to STOP_LOST_MODE.

Union field status. Status specific to the command. Note that some commands do not use this, in particular LOCK, RESET_PASSWORD, REBOOT, and RELINQUISH_OWNERSHIP. In future these commands may use this as well. status can be only one of the following:
clearAppsDataStatus

object (ClearAppsDataStatus)

Output only. Status of the CLEAR_APP_DATA command to clear the data of specified apps from the device. See ClearAppsDataStatus.

startLostModeStatus

object (StartLostModeStatus)

Output only. Status of the START_LOST_MODE command to put the device into lost mode. See StartLostModeStatus.

stopLostModeStatus

object (StopLostModeStatus)

Output only. Status of the STOP_LOST_MODE command to take the device out of lost mode. See StopLostModeStatus.

CommandType

Types of commands.

Enums
COMMAND_TYPE_UNSPECIFIED This value is disallowed.
LOCK Lock the device, as if the lock screen timeout had expired.
RESET_PASSWORD Reset the user's password.
REBOOT Reboot the device. Only supported on fully managed devices running Android 7.0 (API level 24) or higher.
RELINQUISH_OWNERSHIP Removes the work profile and all policies from a company-owned Android 8.0+ device, relinquishing the device for personal use. Apps and data associated with the personal profile(s) are preserved. The device will be deleted from the server after it acknowledges the command.
CLEAR_APP_DATA Clears the application data of specified apps. This is supported on Android 9 and above. Note that an application can store data outside of its application data, for example in external storage or in a user dictionary. See also clearAppsDataParams.
START_LOST_MODE Puts the device into lost mode. Only supported on fully managed devices or organization-owned devices with a managed profile. See also startLostModeParams.
STOP_LOST_MODE Takes the device out of lost mode. Only supported on fully managed devices or organization-owned devices with a managed profile. See also stopLostModeParams.

CommandErrorCode

A command error code. This is a read-only field populated by the server.

Enums
COMMAND_ERROR_CODE_UNSPECIFIED There was no error.
UNKNOWN An unknown error occurred.
API_LEVEL The API level of the device does not support this command.
MANAGEMENT_MODE The management mode (profile owner, device owner, etc.) does not support the command.
INVALID_VALUE The command has an invalid parameter value.
UNSUPPORTED The device doesn't support the command. Updating Android Device Policy to the latest version may resolve the issue.

ResetPasswordFlag

Flags that can be used for the RESET_PASSWORD command type.

Enums
RESET_PASSWORD_FLAG_UNSPECIFIED This value is ignored.
REQUIRE_ENTRY Don't allow other admins to change the password again until the user has entered it.
DO_NOT_ASK_CREDENTIALS_ON_BOOT Don't ask for user credentials on device boot.
LOCK_NOW Lock the device after password reset.

ClearAppsDataParams

Parameters associated with the CLEAR_APP_DATA command to clear the data of specified apps from the device.

JSON representation
{
  "packageNames": [
    string
  ]
}
Fields
packageNames[]

string

The package names of the apps whose data will be cleared when the command is executed.

StartLostModeParams

Parameters associated with the START_LOST_MODE command to put the device into lost mode. At least one of the parameters, not including the organization name, must be provided in order for the device to be put into lost mode.

JSON representation
{
  "lostMessage": {
    object (UserFacingMessage)
  },
  "lostPhoneNumber": {
    object (UserFacingMessage)
  },
  "lostEmailAddress": string,
  "lostStreetAddress": {
    object (UserFacingMessage)
  },
  "lostOrganization": {
    object (UserFacingMessage)
  }
}
Fields
lostMessage

object (UserFacingMessage)

The message displayed to the user when the device is in lost mode.

lostPhoneNumber

object (UserFacingMessage)

The phone number displayed to the user when the device is in lost mode.

lostEmailAddress

string

The email address displayed to the user when the device is in lost mode.

lostStreetAddress

object (UserFacingMessage)

The street address displayed to the user when the device is in lost mode.

lostOrganization

object (UserFacingMessage)

The organization name displayed to the user when the device is in lost mode.

StopLostModeParams

This type has no fields.

Parameters associated with the STOP_LOST_MODE command to take the device out of lost mode.

ClearAppsDataStatus

Status of the CLEAR_APP_DATA command to clear the data of specified apps from the device.

JSON representation
{
  "results": {
    string: {
      object (PerAppResult)
    },
    ...
  }
}
Fields
results

map (key: string, value: object (PerAppResult))

The per-app results, a mapping from package names to the respective clearing result.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

PerAppResult

The result of an attempt to clear the data of a single app.

JSON representation
{
  "clearingResult": enum (ClearingResult)
}
Fields
clearingResult

enum (ClearingResult)

The result of an attempt to clear the data of a single app.

ClearingResult

The result of an attempt to clear the data of a single app.

Enums
CLEARING_RESULT_UNSPECIFIED Unspecified result.
SUCCESS This app’s data was successfully cleared.
APP_NOT_FOUND This app’s data could not be cleared because the app was not found.
APP_PROTECTED This app’s data could not be cleared because the app is protected. For example, this may apply to apps critical to the functioning of the device, such as Google Play Store.
API_LEVEL This app’s data could not be cleared because the device API level does not support this command.

StartLostModeStatus

Status of the START_LOST_MODE command to put the device into lost mode.

JSON representation
{
  "status": enum (Status)
}
Fields
status

enum (Status)

The status. See StartLostModeStatus.

Status

The status. See StartLostModeStatus.

Enums
STATUS_UNSPECIFIED Unspecified. This value is not used.
SUCCESS The device was put into lost mode.
RESET_PASSWORD_RECENTLY The device could not be put into lost mode because the admin reset the device's password recently.
USER_EXIT_LOST_MODE_RECENTLY The device could not be put into lost mode because the user exited lost mode recently.
ALREADY_IN_LOST_MODE The device is already in lost mode.

StopLostModeStatus

Status of the STOP_LOST_MODE command to take the device out of lost mode.

JSON representation
{
  "status": enum (Status)
}
Fields
status

enum (Status)

The status. See StopLostModeStatus.

Status

The status. See StopLostModeStatus.

Enums
STATUS_UNSPECIFIED Unspecified. This value is not used.
SUCCESS The device was taken out of lost mode.
NOT_IN_LOST_MODE The device is not in lost mode.