Offboard device via Defender for Endpoint API Explorer

Have you ever encountered the situation where you need to offboard a device from Defender for Endpoint, but don’t have access to the device? I assume you are. That’s where the Defender for Endpoint API comes in.

Requirements

To offboard a device via the API Explorer (GUI) we need certain permissions. With one of the following Entra ID roles this should work. That’s exactly what this blog post is all about. The Automation part with App registrations can be skipped!

• Global Administrator
• Security Administrator

Offboarding via API Explorer

1: Go to https://security.microsoft.com. Make sure to logon with a account that has Security Admin or Global Admin permissions.

2: Go to Devices -> Find (click) the device you want to offboard. In my case i have multiple entries which lead to non existing devices/installs.

3: Find the Device id and copy it somewhere.

4: Go to Partners and APIs -> API Explorer. Set the action to POST and fill in the query: https://api.securitycenter.microsoft.com/api/machines/{ID}/offboard. Replace the {ID} with the Device ID found in step 3.

Do not click Run query yet! This will result in the following error:

Failure - Status code 400
{
  "error": {
    "code": "InvalidRequestBody",
    "message": "Request body is incorrect",
    "target": "|63d3adbb-475695d59589980d."
  }
}

5: Add the following data to the query: { “Comment”: “Offboard machine by automation” }. You can now run the query. The device should now start the offboarding. The first part of the query (Comment) is case sensitive!

Offboarding a device which is already busy “offboarding” will lead the the following output:

Failure - Status code 400
{
  "error": {
    "code": "ActiveRequestAlreadyExists",
    "message": "Action is already in progress",
    "target": "|5378bce1-4599d6dca3d19860."
  }
}

Keep in mind that there’s a 180 days retention limit active. The offboarded device may exist in your device inventory during this period. Offboarded devices will not use its data anymore for tenant wide calculations/secure scores/etc. This includes vulnerability management!

You might exclude the offboarded/inactive devices from your device inventory by filtering the inventory. Exclude the device and modify your filters.

Offboarding via Automation

While using an automated way/scripting directly to the API, you need at least the following permissions. The should be set on the App registration which needs to be created.

1: Create a new APP registration. Give it a common name. “Defender Offboarding” for example.

2: Go to API permissions -> Add a permission -> APIs my organization uses -> Search for WindowsDefenderATP

3: Pick Application permissions or Delegated permissions. This depends on the usecase. Read about these types of permissions here: Overview of permissions and consent in the Microsoft identity platform – Microsoft identity platform | Microsoft Learn

4: Select the required permissions as stated in the Microsoft docs and click Add permissions.

5: Make sure to give consent!

If required. Create a new Certificate & secret and you’re good to go!

More information can be found here:

Access the Microsoft Defender for Endpoint APIs | Microsoft Learn

Offboard machine API | Microsoft Learn

Create an app to access Microsoft Defender for Endpoint without a user | Microsoft Learn