Skip to content

Latest commit

 

History

History
102 lines (73 loc) · 3.31 KB

set-device-value.md

File metadata and controls

102 lines (73 loc) · 3.31 KB
Raw
title description ms.service ms.author author ms.localizationpriority manager audience ms.collection ms.topic ms.subservice ms.custom search.appverid ms.date
Set device value API
Learn how to specify the value of a device using a Microsoft Defender for Endpoint API.
defender-endpoint
siosulli
siosulli
medium
deniseb
ITPro
m365-security
tier3
must-keep
reference
reference
api
met150
04/17/2024

Set device value API

[!INCLUDE Microsoft Defender XDR rebranding]

Applies to:

Want to experience Microsoft Defender for Endpoint? Sign up for a free trial.

[!includeMicrosoft Defender for Endpoint API URIs for US Government]

[!includeImprove request performance]

API description

Set the device value of a specific Machine.
See assign device values for more information.

Limitations

  1. You can post on devices last seen according to your configured retention period.
  2. Rate limitations for this API are 100 calls per minute and 1500 calls per hour.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs

Permission type Permission Permission display name
Application Machine.ReadWrite.All 'Read and write all machine information'
Delegated (work or school account) Machine.ReadWrite 'Read and write machine information'

Note

When obtaining a token using user credentials:

  • The user needs to have at least the following role permission: 'Manage security setting'. For more (See Create and manage roles for more information)
  • The user needs to have access to the machine, based on machine group settings (See Create and manage machine groups for more information)

HTTP request

POST https://api.security.microsoft.com/api/machines/{machineId}/setDeviceValue

Request headers

Name Type Description
Authorization String Bearer {token}. Required.
Content-Type string application/json. Required.

Request body

In the request body, supply a JSON object with the following parameters:

Parameter Type Description
DeviceValue Enum Device value. Allowed values are: 'Normal', 'Low' and 'High'. Required.

Response

If successful, this method returns 200 - Ok response code and the updated Machine in the response body.

Example

Request

Here is an example of a request that adds machine tag.

POST https://api.security.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/setDeviceValue
{
  "DeviceValue" : "High"
}

[!INCLUDE Microsoft Defender for Endpoint Tech Community]