Microsoft Defender for Endpoint API - Hello World

Applies to:

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


If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.


For better performance, you can use server closer to your geo location:


Get Alerts using a simple PowerShell script

How long it takes to go through this example?

It only takes 5 minutes done in two steps:

  • Application registration
  • Use examples: only requires copy/paste of a short PowerShell script

Do I need a permission to connect?

For the Application registration stage, you must have a Global administrator role in your Microsoft Entra tenant.

Step 1 - Create an App in Microsoft Entra ID

  1. Log on to Azure with your Global administrator user.

  2. Navigate to Microsoft Entra ID > App registrations > New registration.

    The App registrations option under the Manage pane in the Microsoft Entra admin center

  3. In the registration form, choose a name for your application and then click Register.

  4. Allow your Application to access Defender for Endpoint and assign it 'Read all alerts' permission:

    • On your application page, click API Permissions > Add permission > APIs my organization uses > type WindowsDefenderATP and click on WindowsDefenderATP.


      WindowsDefenderATP does not appear in the original list. You need to start writing its name in the text box to see it appear.

      The API permissions option under the Manage pane in the Microsoft Entra admin center

    • Choose Application permissions > Alert.Read.All > Click on Add permissions.

      The permission type and settings panes in the Request API permissions page


      You need to select the relevant permissions. 'Read All Alerts' is only an example!

      For example:

      • To run advanced queries, select 'Run advanced queries' permission.
      • To isolate a machine, select 'Isolate machine' permission.
      • To determine which permission you need, please look at the Permissions section in the API you are interested to call.
  5. Click Grant consent.


    Every time you add permission, you must click on Grant consent for the new permission to take effect.

    The grant permission consent option in the Microsoft Entra admin center

  6. Add a secret to the application.

    Click Certificates & secrets, add description to the secret and click Add.


    After click Add, copy the generated secret value. You won't be able to retrieve after you leave!

    The Certificates & secrets menu item in the Manage pane in the Microsoft Entra admin center

  7. Write down your application ID and your tenant ID.

    On your application page, go to Overview and copy the following:

    The application details pane under the Overview menu item in the Microsoft Entra admin center

Done! You have successfully registered an application!

Step 2 - Get a token using the App and use this token to access the API.

  • Copy the script below to PowerShell ISE or to a text editor, and save it as Get-Token.ps1.

  • Running this script will generate a token and will save it in the working folder under the name Latest-token.txt.

    # That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
    # Paste below your Tenant ID, App ID and App Secret (App key).
    $tenantId = '' ### Paste your tenant ID here
    $appId = '' ### Paste your Application ID here
    $appSecret = '' ### Paste your Application secret here
    $resourceAppIdUri = ''
    $oAuthUri = "$TenantId/oauth2/token"
    $authBody = [Ordered] @{
         resource = "$resourceAppIdUri"
         client_id = "$appId"
         client_secret = "$appSecret"
         grant_type = 'client_credentials'
    $authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
    $token = $authResponse.access_token
    Out-File -FilePath "./Latest-token.txt" -InputObject $token
    return $token
  • Sanity Check:

    • Run the script.
    • In your browser go to:
    • Copy the token (the content of the Latest-token.txt file).
    • Paste in the top box.
    • Look for the "roles" section. Find the Alert.Read.All role.

    The Decoded Token pane for

Let's get the Alerts!

  • The script below will use Get-Token.ps1 to access the API and will get the past 48 hours Alerts.

  • Save this script in the same folder you saved the previous script Get-Token.ps1.

  • The script creates two files (json and csv) with the data in the same folder as the scripts.

    # Returns Alerts created in the past 48 hours.
    $token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1
    # Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
    $dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")
    # The URL contains the type of query and the time filter we create above
    # Read more about [other query options and filters](
    $url = "`$filter=alertCreationTime ge $dateTime"
    # Set the WebRequest headers
    $headers = @{
        'Content-Type' = 'application/json'
        Accept = 'application/json'
        Authorization = "Bearer $token"
    # Send the webrequest and get the results.
    $response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop
    # Extract the alerts from the results.
    $alerts =  ($response | ConvertFrom-Json).value | ConvertTo-Json
    # Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
    $dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}
    # Save the result as json and as csv
    $outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
    $outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"
    Out-File -FilePath $outputJsonPath -InputObject $alerts
    ($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation

You're all done! You have just successfully:

  • Created and registered and application
  • Granted permission for that application to read alerts
  • Connected the API
  • Used a PowerShell script to return alerts created in the past 48 hours


Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.