windows-itpro-docs/windows/security/threat-protection/windows-defender-atp/api-hello-world.md

title, description, keywords, search.product, ms.prod, ms.mktglfcycl, ms.sitesec, ms.pagetype, ms.author, author, ms.localizationpriority, manager, audience, ms.collection, ms.topic

title	description	keywords	search.product	ms.prod	ms.mktglfcycl	ms.sitesec	ms.pagetype	ms.author	author	ms.localizationpriority	manager	audience	ms.collection	ms.topic
Advanced Hunting API	Use this API to run advanced queries	apis, supported apis, advanced hunting, query	eADQiWindows 10XVcnh	w10	deploy	library	security	macapara	mjcaparas	medium	dansimp	ITPro	M365-security-compliance	article

Windows Defender ATP API - Hello World

Applies to:

• Windows Defender Advanced Threat Protection (Windows Defender ATP)

Want to experience Windows Defender ATP? Sign up for a free trial.

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 App registration stage, you must have a Global administrator role in your Azure Active Directory (Azure AD) tenant.

Step 1 - Create an App in Azure Active Directory

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

2. Navigate to Azure Active Directory > App registrations > New application registration.

   

3. In the registration form, enter the following information, then click Create.

   • Name: Choose your own name.
   • Application type: Web app / API
   • Redirect URI: https://127.0.0.1

   

4. Allow your App to access Windows Defender ATP and assign it 'Read all alerts' permission:

   • Click Settings > Required permissions > Add.

   

   • Click Select an API > WindowsDefenderATP, then click Select.

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

   

   • Click Select permissions > Read all alerts > Select.

   

   • Click Done

   

   • Click Grant permissions

   Note: Every time you add permission you must click on Grant permissions.

   

5. Create a key for your App:

   • Click Keys, type a key name and click Save.

   

6. Write down your App ID and your Tenant ID:

   • App ID:

   

   • Tenant ID: Navigate to Azure Active Directory > Properties

   

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 app ID here
$appSecret = '' ### Paste your app key here
 
$resourceAppIdUri = 'https://api.securitycenter.windows.com'
$oAuthUri = "https://login.windows.net/$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: https://jwt.ms/
  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.

Lets 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 at   Https://TBD- add the documentation link
$url = "https://api.securitycenter.windows.com/api/alerts?`$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

Related topic

• Windows Defender ATP APIs
• Access Windows Defender ATP with application context
• Access Windows Defender ATP with user context