Offboarding a device from Microsoft Defender for Endpoint can be essential for various reasons, such as decommissioning a device or troubleshooting. This guide will walk you through the steps to offboard a device using the Defender for Endpoint API Explorer.
Prerequisites
Before you begin, ensure you have the following:
- Permissions: You need to have either Security Administrator or Global Administrator permissions.
- Device ID: The unique identifier for the device you want to offboard.
Steps to Offboard a Device
Log in to the Security Center:
- Navigate to Microsoft Security Center and log in with an account that has the necessary permissions.
Locate the Device:
- Go to the Devices section.
- Find and click on the device you want to offboard.
- Copy the Device ID from the URL. It is typically a 40-digit alphanumeric string.
Access API Explorer:
- In the left pane, navigate to Partners and APIs and then select API Explorer.
Set Up the API Request:
- Change the HTTP method to
POST. - Enter the following URL in the API Explorer:
https://api.securitycenter.microsoft.com/api/machines/{DeviceID}/offboardReplace {DeviceID} with the actual Device ID you copied earlier.
Add Request Body:
- In the request body, add the following JSON object:
- Note that the Comment field is case-sensitive.
{
"Comment": "Offboard machine by automation"
}
Run the Query:
- Click on Run Query to execute the offboarding process.
- If successful, the device will start the offboarding process. If the device is already in the process of being offboarded, you might receive an error indicating that an active request already exists.
Important Considerations
- Retention Period: Offboarded devices may remain in your device inventory for up to 180 days. During this period, they will not contribute to tenant-wide calculations or secure scores.
- Permissions: Ensure that the account used has the appropriate permissions to avoid errors during the process.
By following these steps, you can efficiently offboard a device from Microsoft Defender for Endpoint using the API Explorer. This method is particularly useful when you do not have direct access to the device but need to ensure it is properly offboarded from your security environment.
Feel free to share your experiences or any additional tips in the comments below!
I hope this guide helps you with offboarding devices via the Defender for Endpoint API Explorer. If you have any questions or run into issues, don’t hesitate to ask!
Reference:
Offboard machine API – Microsoft Defender for Endpoint | Microsoft Learn
Access the Microsoft Defender for Endpoint APIs – Microsoft Defender for Endpoint | Microsoft Learn
Create an app to access Microsoft Defender for Endpoint without a user – Microsoft Defender for Endpoint | Microsoft Learn
