Merge branch 'atp-api-danm' of https://cpubwin.visualstudio.com/_git/it-client into atp-api-danm

windows/security/threat-protection/windows-defender-atp/TOC.md

@@ -157,6 +157,7 @@
 ##### [Schedule advanced Hunting using Microsoft Flow](run-advanced-query-sample-ms-flow.md)
 ##### [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
 ##### [Advanced Hunting using Python](run-advanced-query-sample-python.md)
+##### [Create custom Power BI reports](run-advanced-query-sample-power-bi.md)
 
 
 ### [Use the Windows Defender ATP exposed APIs](exposed-apis-windows-defender-advanced-threat-protection.md)

windows/security/threat-protection/windows-defender-atp/collect-investigation-package-windows-defender-advanced-threat-protection-new.md

@@ -31,6 +31,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.CollectForensics |	'Collect forensics'
+Delegated (work or school account) |	Machine.CollectForensics |	'Collect forensics'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/create-alert-by-reference-windows-defender-advanced-threat-protection-new.md

@@ -30,6 +30,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Alerts.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/exposed-apis-create-app-nativeapp.md

@@ -41,6 +41,11 @@ In general, you’ll need to take the following steps to use the APIs:
 
 This page explains how to create an app, get an access token to Windows Defender ATP and validate the token includes the required permission.
 
+**Note**: When accessing WDATP API on behalf of a user, you will need the correct app permission and user permission.
+If you are not familiar with user permissions on WDATP, please refer to [Manage portal access using role-based access control](rbac-windows-defender-advanced-threat-protection.md)
+
+**Rule of thumb for user permissions:** If you have the permission to perform an action in the portal, you have the permission to perform the action in the API. 
+
 ## Create an app
 
 1.	Log on to [Azure](https://portal.azure.com).
@@ -51,16 +56,16 @@ This page explains how to create an app, get an access token to Windows Defender
 
 3.	In the Create window, enter the following information then click **Create**.
 
-    ![Image of Create application window](images/webapp-create.png)
+    ![Image of Create application window](images/nativeapp-create.png)
 
-    - **Name:** WdatpEcosystemPartner
+    - **Name:** -Your app name-
-    - **Application type:** Web app / API
+    - **Application type:** Native
-    - **Redirect URI:** `https://WdatpEcosystemPartner.com` (The URL where user can sign in and use your app. You can change this URL later.)
+    - **Redirect URI:** `https://127.0.0.1`
 
 
 4.	Click **Settings** > **Required permissions** > **Add**.
 
-    ![Image of new app in Azure](images/webapp-add-permission.png)
+    ![Image of new app in Azure](images/nativeapp-add-permission.png)
 
 5.	Click **Select an API** > **WindowsDefenderATP**, then click **Select**.
 	
@@ -68,54 +73,35 @@ This page explains how to create an app, get an access token to Windows Defender
 
     ![Image of API access and API selection](images/webapp-add-permission-2.png)
 
-6. Click **Select permissions** > **Run advanced queries** > **Select**.
+6. Click **Select permissions** > check **Read alerts** & **Collect forensics** > **Select**.
 	
-	**Important note**: You need to select the relevant permission. 'Run advanced queries' is only an example!
+	**Important note**: You need to select the relevant permissions. 'Read alerts' and 'Collect forensics' are only an example!
 
-    ![Image of select permissions](images/webapp-select-permission.png)
+    ![Image of select permissions](images/nativeapp-select-permissions.png)
+
+	For instance,
+
+       - In order to [run advanced queries](run-advanced-query-api.md), check 'Run advanced queries' permission
+       - In order to [isolate a machine](isolate-machine-windows-defender-advanced-threat-protection-new.md), check 'Isolate machine' permission
+
+       To determine which permission you need, please look at the **Permissions** section in the API you are interested to call.
 
-	- In order to send telemetry events to WDATP, check 'Write timeline events' permission
-	- In order to send TI events to WDATP, check 'Read and write IOCs belonging to the app' permission
-	- In order to run advanced queries in WDATP, check 'Run advanced queries' permission
 
 7. Click **Done**
 
-    ![Image of add permissions completion](images/webapp-add-permission-end.png)
+    ![Image of add permissions completion](images/nativeapp-add-permissions-end.png)
 
-8. Click **Keys** and type a key name and click **Save**.
+8. Click **Grant permissions**
 
-	**Important**: After you save, **copy the key value**. You won't be able to retrieve after you leave!
+	In order to add the new selected permissions to the app, the Admin's tenant must press on the **Grant permissions** button.
 
-    ![Image of create app key](images/webapp-create-key.png)
+	If in the future you will want to add more permission to the app, you will need to press on the **Grant permissions** button again so the changes will take effect.
+
+	![Image of Grant permissions](images/webapp-grant-permissions.png)
 
 9. Write down your application ID.
     
-	![Image of app ID](images/webapp-get-appid.png)
+	![Image of app ID](images/nativeapp-get-appid.png)
-
-9. Set your application to be multi-tenanted
-	
-	This is **required** for 3rd party apps (i.e., if you create an application that is intended to run in multiple customers tenant).
-
-	This is **not required** if you create a service that you want to run in your tenant only (i.e., if you create an application for your own usage that will only interact with your own data)​
-
-	Click **Properties** > **Yes** > **Save**.
-
-	![Image of multi tenant](images/webapp-edit-multitenant.png)
-
-
-## Application consent
-
-You need your application to be approved in each tenant where you intend to use it. This is because your application interacts with WDATP application on behalf of your customer.
-
-You (or your customer if you are writing a 3rd party application) need to click the consent link and approve your application. The consent should be done with a user who has admin privileges in the active directory.
-
-Consent link is of the form: 
-
-```
-https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true​
-```
-
-where 00000000-0000-0000-0000-000000000000​ should be replaced with your Azure application ID
 
 
 ## Get an access token
@@ -134,57 +120,52 @@ For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.co
 	using Microsoft.IdentityModel.Clients.ActiveDirectory;
 	```
 
-- Copy/Paste the below code in your application (do not forget to update the 3 variables: ```tenantId, appId, appSecret```)
+- Copy/Paste the below code in your application (pay attention to the comments in the code)
 
 	```
+	const string authority = "https://login.windows.net";
+	const string wdatpResourceId = "https://api.securitycenter.windows.com/";
+
 	string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
 	string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
-	string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here
 
-	const string aadUri = "https://login.windows.net";
+	string username = "SecurityAdmin123@microsoft.com"; // Paste your username here
-	const string wdatpResourceId = "https://securitycenter.onmicrosoft.com/windowsatpservice";
+	string password = GetPasswordFromSafePlace(); // Paste your own password here for a test, and then store it in a safe place! 
 
-	AuthenticationContext auth = new AuthenticationContext($"{aadUri}/{tenantId}/");
+	UserPasswordCredential userCreds = new UserPasswordCredential(username, password);
-	ClientCredential clientCredential = new ClientCredential(appId, appSecret);
+
-	AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
+	AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}");
+	AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, appId, userCreds).GetAwaiter().GetResult();
 	string token = authenticationResult.AccessToken;
 	```
 
-### Using PowerShell 
-
-Refer to [Get token using PowerShell](run-advanced-query-sample-powershell.md#get-token)
-
-### Using Python
-
-Refer to [Get token using Python](run-advanced-query-sample-python.md#get-token)
-
-### Using Curl
-
-> [!NOTE]
-> The below procedure supposed Curl for Windows is already installed on your computer
-
-- Open a command window
-- ​Set CLIENT_ID to your Azure application ID
-- Set CLIENT_SECRET to your Azure application secret
-- Set TENANT_ID to the Azure tenant ID of the customer that wants to use your application to access WDATP application
-- Run the below command:
-
-```
-curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -d "grant_type=client_credentials" -d "client_id=%CLIENT_ID%" -d "scope=https://securitycenter.onmicrosoft.com/windowsatpservice​/.default" -d "client_secret=%CLIENT_SECRET%" "https://login.microsoftonline.com/%TENANT_ID​%/oauth2/v2.0/token" -k​
-```
-
-You will get an answer of the form:
-
-```
-{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn <truncated> aWReH7P0s0tjTBX8wGWqJUdDA"}
-```
-
 ## Validate the token
 
-- Copy/paste into [JWT](https://jwt.io/) the token you get in the previous step 
+Sanity check to make sure you got a correct token:
-- Validate you get a 'roles' claim with the desired permission, as shown in the below screenshot
+- Copy/paste into [JWT](https://jwt.ms) the token you get in the previous step in order to decode it
+- Validate you get a 'scp' claim with the desired app permissions
+- In the screenshot below you can see a decoded token acquired from the app in the tutorial:
 
-![Image of token validation](images/webapp-validate-token.png)
+![Image of token validation](images/nativeapp-decoded-token.png)
+
+## Use the token to access Windows Defender ATP API
+
+- Choose the API you want to use - [Supported Windows Defender ATP APIs](exposed-apis-list.md)
+- Set the Authorization header in the HTTP request you send to "Bearer {token}" (Bearer is the Authorization scheme)
+- The Expiration time of the token is 1 hour (you can send more then one request with the same token)
+
+- Example of sending a request to get a list of alerts **using C#** 
+	```
+	var httpClient = new HttpClient();
+
+	var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.windows.com/api/alerts");
+
+	request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
+
+	var response = await httpClient.SendAsync(request).ConfigureAwait(false);
+
+	// Do something useful with the response
+	```
 
 ## Related topics
 - [Windows Defender ATP APIs](exposed-apis-intro.md)

windows/security/threat-protection/windows-defender-atp/exposed-apis-create-app-webapp.md

@@ -74,25 +74,36 @@ This page explains how to create an app, get an access token to Windows Defender
 
     ![Image of select permissions](images/webapp-select-permission.png)
 
-	- In order to send telemetry events to WDATP, check 'Write timeline events' permission
+	For instance,
-	- In order to send TI events to WDATP, check 'Read and write IOCs belonging to the app' permission
+
-	- In order to run advanced queries in WDATP, check 'Run advanced queries' permission
+	- In order to [run advanced queries](run-advanced-query-api.md), check 'Run advanced queries' permission
+	- In order to [isolate a machine](isolate-machine-windows-defender-advanced-threat-protection-new.md), check 'Isolate machine' permission
+
+	To determine which permission you need, please look at the **Permissions** section in the API you are interested to call.
 
 7. Click **Done**
 
     ![Image of add permissions completion](images/webapp-add-permission-end.png)
 
-8. Click **Keys** and type a key name and click **Save**.
+8. Click **Grant permissions**
+
+	In order to add the new selected permissions to the app, the Admin's tenant must press on the **Grant permissions** button.
+
+	If in the future you will want to add more permission to the app, you will need to press on the **Grant permissions** button again so the changes will take effect.
+
+	![Image of Grant permissions](images/webapp-grant-permissions.png)
+
+9. Click **Keys** and type a key name and click **Save**.
 
 	**Important**: After you save, **copy the key value**. You won't be able to retrieve after you leave!
 
     ![Image of create app key](images/webapp-create-key.png)
 
-9. Write down your application ID.
+10. Write down your application ID.
     
 	![Image of app ID](images/webapp-get-appid.png)
 
-9. Set your application to be multi-tenanted
+11. Set your application to be multi-tenanted
 	
 	This is **required** for 3rd party apps (i.e., if you create an application that is intended to run in multiple customers tenant).
 
@@ -103,13 +114,13 @@ This page explains how to create an app, get an access token to Windows Defender
 	![Image of multi tenant](images/webapp-edit-multitenant.png)
 
 
-## Application consent
+**Note**:
 
-You need your application to be approved in each tenant where you intend to use it. This is because your application interacts with WDATP application on behalf of your customer.
+	You need your application to be approved in each tenant where you intend to use it. This is because your application interacts with WDATP application on behalf of your customer.
 
-You (or your customer if you are writing a 3rd party application) need to click the consent link and approve your application. The consent should be done with a user who has admin privileges in the active directory.
+	You (or your customer if you are writing a 3rd party application) need to click the consent link and approve your application. The consent should be done with a user who has admin privileges in the active directory.
 
-Consent link is of the form: 
+	Consent link is of the form: 
 
 ```
 https://login.microsoftonline.com/common/oauth2/authorize?prompt=consent&client_id=00000000-0000-0000-0000-000000000000&response_type=code&sso_reload=true​
@@ -139,12 +150,12 @@ For more details on AAD token, refer to [AAD tutorial](https://docs.microsoft.co
 	```
 	string tenantId = "00000000-0000-0000-0000-000000000000"; // Paste your own tenant ID here
 	string appId = "11111111-1111-1111-1111-111111111111"; // Paste your own app ID here
-	string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here
+	string appSecret = "22222222-2222-2222-2222-222222222222"; // Paste your own app secret here for a test, and then store it in a safe place! 
 
-	const string aadUri = "https://login.windows.net";
+	const string authority = "https://login.windows.net";
-	const string wdatpResourceId = "https://securitycenter.onmicrosoft.com/windowsatpservice";
+	const string wdatpResourceId = "https://api.securitycenter.windows.com/";
 
-	AuthenticationContext auth = new AuthenticationContext($"{aadUri}/{tenantId}/");
+	AuthenticationContext auth = new AuthenticationContext($"{authority}/{tenantId}/");
 	ClientCredential clientCredential = new ClientCredential(appId, appSecret);
 	AuthenticationResult authenticationResult = auth.AcquireTokenAsync(wdatpResourceId, clientCredential).GetAwaiter().GetResult();
 	string token = authenticationResult.AccessToken;
@@ -181,11 +192,31 @@ You will get an answer of the form:
 
 ## Validate the token
 
-- Copy/paste into [JWT](https://jwt.io/) the token you get in the previous step 
+Sanity check to make sure you got a correct token:
-- Validate you get a 'roles' claim with the desired permission, as shown in the below screenshot
+- Copy/paste into [JWT](https://jwt.ms) the token you get in the previous step in order to decode it
+- Validate you get a 'roles' claim with the desired permissions
+- In the screenshot below you can see a decoded token acquired from an app with permissions to all of Wdatp's roles:
 
-![Image of token validation](images/webapp-validate-token.png)
+![Image of token validation](images/webapp-decoded-token.png)
 
+## Use the token to access Windows Defender ATP API
+
+- Choose the API you want to use - [Supported Windows Defender ATP APIs](exposed-apis-list.md)
+- Set the Authorization header in the Http request you send to "Bearer {token}" (Bearer is the Authorization scheme)
+- The Expiration time of the token is 1 hour (you can send more then one request with the same token)
+
+- Example of sending a request to get a list of alerts **using C#** 
+	```
+	var httpClient = new HttpClient();
+
+	var request = new HttpRequestMessage(HttpMethod.Get, "https://api.securitycenter.windows.com/api/alerts");
+
+	request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
+
+	var response = await httpClient.SendAsync(request).ConfigureAwait(false);
+
+	// Do something useful with the response
+	```
 ## Related topics
 - [Windows Defender ATP APIs](exposed-apis-intro.md)
 - [Supported Windows Defender ATP APIs](exposed-apis-list.md)

windows/security/threat-protection/windows-defender-atp/get-alert-info-by-id-windows-defender-advanced-threat-protection-new.md

@@ -31,6 +31,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Alert.Read.All |	'Read all alerts'
 Application |	Alert.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.Read | 'Read alerts'
+Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-alert-related-domain-info-windows-defender-advanced-threat-protection-new.md

@@ -30,6 +30,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	URL.Read.All |	'Read URLs'
+Delegated (work or school account) | URL.Read.All |	'Read URLs'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-alert-related-files-info-windows-defender-advanced-threat-protection-new.md

@@ -30,6 +30,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	File.Read.All |	'Read file profiles'
+Delegated (work or school account) | File.Read.All |	'Read file profiles'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-alert-related-ip-info-windows-defender-advanced-threat-protection-new.md

@@ -31,6 +31,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Ip.Read.All |	'Read IP address profiles'
+Delegated (work or school account) | Ip.Read.All |	'Read IP address profiles'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-alert-related-machine-info-windows-defender-advanced-threat-protection-new.md

@@ -30,8 +30,10 @@ One of the following permissions is required to call this API. To learn more, in
 
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
-Application |	Machine.Read.All |	'Read all machine profiles'
+Application |	Machine.Read.All |	'Read all machine information'
 Application |	Machine.ReadWrite.All |	'Read and write all machine information'
+Delegated (work or school account) | Machine.Read | 'Read machine information'
+Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-alert-related-user-info-windows-defender-advanced-threat-protection-new.md

@@ -31,6 +31,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	User.Read.All |	'Read user profiles'
+Delegated (work or school account) | User.Read.All | 'Read user profiles'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-alerts-windows-defender-advanced-threat-protection-new.md

@@ -33,6 +33,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Alert.Read.All |	'Read all alerts'
 Application |	Alert.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.Read | 'Read alerts'
+Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-domain-related-alerts-windows-defender-advanced-threat-protection-new.md

@@ -32,6 +32,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Alert.Read.All |	'Read all alerts'
 Application |	Alert.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.Read | 'Read alerts'
+Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-domain-related-machines-windows-defender-advanced-threat-protection-new.md

@@ -32,6 +32,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Read.All |	'Read all machine profiles'
 Application |	Machine.ReadWrite.All |	'Read and write all machine information'
+Delegated (work or school account) | Machine.Read | 'Read machine information'
+Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-domain-statistics-windows-defender-advanced-threat-protection-new.md

@@ -30,7 +30,8 @@ One of the following permissions is required to call this API. To learn more, in
 
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
-Application |	URL.Read.All |	'Read all machine profiles'
+Application |	URL.Read.All |	'Read URLs'
+Delegated (work or school account) | URL.Read.All |	'Read URLs'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-file-information-windows-defender-advanced-threat-protection-new.md

@@ -32,6 +32,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	File.Read.All |	'Read all file profiles'
+Delegated (work or school account) | File.Read.All |	'Read all file profiles'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-file-related-alerts-windows-defender-advanced-threat-protection-new.md

@@ -32,6 +32,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Alert.Read.All |	'Read all alerts'
 Application |	Alert.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.Read | 'Read alerts'
+Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-file-related-machines-windows-defender-advanced-threat-protection-new.md

@@ -32,6 +32,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Read.All |	'Read all machine profiles'
 Application |	Machine.ReadWrite.All |	'Read and write all machine information'
+Delegated (work or school account) | Machine.Read | 'Read machine information'
+Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-file-statistics-windows-defender-advanced-threat-protection-new.md

@@ -31,6 +31,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	File.Read.All |	'Read file profiles'
+Delegated (work or school account) | File.Read.All | 'Read file profiles'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-ip-related-alerts-windows-defender-advanced-threat-protection-new.md

@@ -32,6 +32,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Alert.Read.All |	'Read all alerts'
 Application |	Alert.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.Read | 'Read alerts'
+Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-ip-related-machines-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Read.All |	'Read all machine profiles'
 Application |	Machine.ReadWrite.All |	'Read and write all machine information'
+Delegated (work or school account) | Machine.Read | 'Read machine information'
+Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-ip-statistics-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Ip.Read.All |	'Read IP address profiles'
+Delegated (work or school account) | Ip.Read.All |	'Read IP address profiles'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-machine-by-id-windows-defender-advanced-threat-protection-new.md

@@ -30,6 +30,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Read.All |	'Read all machine profiles'
 Application |	Machine.ReadWrite.All |	'Read and write all machine information'
+Delegated (work or school account) | Machine.Read | 'Read machine information'
+Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-machine-log-on-users-windows-defender-advanced-threat-protection-new.md

@@ -29,7 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	User.Read.All |	'Read user profiles'
-
+Delegated (work or school account) | User.Read.All | 'Read user profiles'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-machine-related-alerts-windows-defender-advanced-threat-protection-new.md

@@ -30,6 +30,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Alert.Read.All |	'Read all alerts'
 Application |	Alert.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.Read | 'Read alerts'
+Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-machineaction-object-windows-defender-advanced-threat-protection-new.md

@@ -30,6 +30,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Read.All |	'Read all machine profiles'
 Application |	Machine.ReadWrite.All |	'Read and write all machine information'
+Delegated (work or school account) | Machine.Read | 'Read machine information'
+Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-machineactions-collection-windows-defender-advanced-threat-protection-new.md

@@ -30,6 +30,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Read.All |	'Read all machine profiles'
 Application |	Machine.ReadWrite.All |	'Read and write all machine information'
+Delegated (work or school account) | Machine.Read | 'Read machine information'
+Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-machines-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Read.All |	'Read all machine profiles'
 Application |	Machine.ReadWrite.All |	'Read and write all machine information'
+Delegated (work or school account) | Machine.Read | 'Read machine information'
+Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-package-sas-uri-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.CollectForensics |	'Collect forensics'
+Delegated (work or school account) | Machine.CollectForensics |	'Collect forensics'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-user-related-alerts-windows-defender-advanced-threat-protection-new.md

@@ -30,6 +30,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Alert.Read.All |	'Read all alerts'
 Application |	Alert.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.Read | 'Read alerts'
+Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/get-user-related-machines-windows-defender-advanced-threat-protection-new.md

@@ -30,6 +30,8 @@ Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Read.All |	'Read all machine profiles'
 Application |	Machine.ReadWrite.All |	'Read and write all machine information'
+Delegated (work or school account) | Machine.Read | 'Read machine information'
+Delegated (work or school account) | Machine.ReadWrite | 'Read and write machine information'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/is-domain-seen-in-org-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Url.Read.All |	'Read URLs'
+Delegated (work or school account) | URL.Read.All |	'Read URLs'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/is-ip-seen-org-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Ip.Read.All |	'Read IP address profiles'
+Delegated (work or school account) | Ip.Read.All |	'Read IP address profiles'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/isolate-machine-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Isolate |	'Isolate machine'
+Delegated (work or school account) | Machine.Isolate |	'Isolate machine'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/offboard-machine-api-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Offboard |	'Offboard machine'
+Delegated (work or school account) |	Machine.Offboard |	'Offboard machine'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/powerbi-reports-windows-defender-advanced-threat-protection.md

@@ -200,5 +200,10 @@ There are a couple of tabs on the report that's generated:
 In general, if you know of a specific threat name, CVE, or KB, you can identify machines with unpatched vulnerabilities that might be leveraged by threats. This report also helps you determine whether machine-level mitigations are configured correctly on the machines and prioritize those that might need attention.
 
 
+## Related topic
+- [**Beta** Create custom Power BI reports](run-advanced-query-sample-power-bi.md)
+
+
+
 
 

windows/security/threat-protection/windows-defender-atp/restrict-code-execution-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.RestrictExecution |	'Restrict code execution'
+Delegated (work or school account) | Machine.RestrictExecution | 'Restrict code execution'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/run-advanced-query-api.md

@@ -36,6 +36,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	AdvancedQuery.Read.All |	'Run advanced queries'
+Delegated (work or school account) | AdvancedQuery.Read | 'Run advanced queries'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/run-advanced-query-sample-power-bi.md

@@ -0,0 +1,131 @@
+---
+title: Advanced Hunting API
+description: Use this API to run advanced queries
+keywords: apis, supported apis, advanced hunting, query
+search.product: eADQiWindows 10XVcnh
+ms.prod: w10
+ms.mktglfcycl: deploy
+ms.sitesec: library
+ms.pagetype: security
+ms.author: macapara
+author: mjcaparas
+ms.localizationpriority: medium
+ms.date: 30/07/2018
+---
+
+# Create custom reports using Power BI
+
+Run advanced queries and show results in Microsoft Power BI. Please read about [Advanced Hunting API](run-advanced-query-api.md) before.
+
+In this section we share Power BI query sample to run a query using application token.
+
+>**Prerequisite**: You first need to [create an app](exposed-apis-intro.md).
+
+## Run a query
+
+- Open Microsoft Power BI
+
+- Click **Get Data** > **Blank Query**
+
+    ![Image of create blank query](images/power-bi-create-blank-query.png)
+
+- Click **Advanced Editor**
+
+    ![Image of open advanced editor](images/power-bi-open-advanced-editor.png)
+
+- Copy the below and paste it in the editor, after you update the values of _TenantId, _AppId, _AppSecret, _Query
+
+	```
+	let 
+
+		TenantId = "00000000-0000-0000-0000-000000000000", // Paste your own tenant ID here
+		AppId = "11111111-1111-1111-1111-111111111111", // Paste your own app ID here
+		AppSecret = "22222222-2222-2222-2222-222222222222", // Paste your own app secret here
+		Query = "MachineInfo | where EventTime > ago(7d) | summarize EventCount=count(), LastSeen=max(EventTime) by MachineId", // Paste your own query here
+    
+		ResourceAppIdUrl = "https://securitycenter.onmicrosoft.com/windowsatpservice",
+		OAuthUrl = Text.Combine({"https://login.windows.net/", TenantId, "/oauth2/token"}, ""),
+
+		Resource = Text.Combine({"resource", Uri.EscapeDataString(ResourceAppIdUrl)}, "="),
+		ClientId = Text.Combine({"client_id", AppId}, "="),
+		ClientSecret = Text.Combine({"client_secret", Uri.EscapeDataString(AppSecret)}, "="),
+		GrantType = Text.Combine({"grant_type", "client_credentials"}, "="),
+	
+		Body = Text.Combine({Resource, ClientId, ClientSecret, GrantType}, "&"),
+
+		AuthResponse= Json.Document(Web.Contents(OAuthUrl, [Content=Text.ToBinary(Body)])),
+		AccessToken= AuthResponse[access_token],
+		Bearer = Text.Combine({"Bearer", AccessToken}, " "),
+    
+		AdvancedHuntingUrl = "https://api.securitycenter.windows.com/advancedqueries/query",
+    
+		Response = Json.Document(Web.Contents(
+			AdvancedHuntingUrl, 
+			[
+				Headers = [#"Content-Type"="application/json", #"Accept"="application/json", #"Authorization"=Bearer],
+				Content=Json.FromValue(Query)
+			]
+		)),
+
+		TypeMap = #table(
+			{ "Type", "PowerBiType" },
+			{
+				{ "Double",   Double.Type },
+				{ "Int64",    Int64.Type },
+				{ "Int32",    Int32.Type },
+				{ "Int16",    Int16.Type },
+				{ "UInt64",   Number.Type },
+				{ "UInt32",   Number.Type },
+				{ "UInt16",   Number.Type },
+				{ "Byte",     Byte.Type },
+				{ "Single",   Single.Type },
+				{ "Decimal",  Decimal.Type },
+				{ "TimeSpan", Duration.Type },
+				{ "DateTime", DateTimeZone.Type },
+				{ "String",   Text.Type },
+				{ "Boolean",  Logical.Type },
+				{ "SByte",    Logical.Type },
+				{ "Guid",     Text.Type }
+			}),
+
+		Schema = Table.FromRecords(Response[Schema]),
+		TypedSchema = Table.Join(Table.SelectColumns(Schema, {"Name", "Type"}), {"Type"}, TypeMap , {"Type"}),
+		Results = Response[Results],
+		Rows = Table.FromRecords(Results, Schema[Name]),
+		Table = Table.TransformColumnTypes(Rows, Table.ToList(TypedSchema, (c) => {c{0}, c{2}}))
+        
+	in Table
+
+	```
+
+- Click **Done**
+
+    ![Image of create advanced query](images/power-bi-create-advanced-query.png)
+
+- Click **Edit Credentials**
+
+    ![Image of edit credentials](images/power-bi-edit-credentials.png)
+
+- Select **Anonymous** and click **Connect**
+
+    ![Image of set credentials](images/power-bi-set-credentials.png)
+
+- Repeat the previous step for the second URL
+
+- Click **Continue**
+
+    ![Image of edit data privacy](images/power-bi-edit-data-privacy.png)
+
+- Select the privacy level you want and click **Save**
+
+    ![Image of set data privacy](images/power-bi-set-data-privacy.png)
+
+- View the results of your query
+
+    ![Image of query results](images/power-bi-query-results.png)
+
+## Related topic
+- [Windows Defender ATP APIs](exposed-apis-intro.md)
+- [Advanced Hunting API](run-advanced-query-api.md)
+- [Advanced Hunting using PowerShell](run-advanced-query-sample-powershell.md)
+- [Schedule Advanced Hunting](run-advanced-query-sample-ms-flow.md)

windows/security/threat-protection/windows-defender-atp/run-av-scan-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Scan |	'Scan machine'
+Delegated (work or school account) |	Machine.Scan |	'Scan machine'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/unisolate-machine-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.Isolate |	'Isolate machine'
+Delegated (work or school account) |	Machine.Isolate |	'Isolate machine'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/unrestrict-code-execution-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Machine.RestrictExecution |	'Restrict code execution'
+Delegated (work or school account) | Machine.RestrictExecution | 'Restrict code execution'
 
 ## HTTP request
 ```

windows/security/threat-protection/windows-defender-atp/update-alert-windows-defender-advanced-threat-protection-new.md

@@ -29,6 +29,7 @@ One of the following permissions is required to call this API. To learn more, in
 Permission type |	Permission	|	Permission display name
 :---|:---|:---
 Application |	Alerts.ReadWrite.All |	'Read and write all alerts'
+Delegated (work or school account) | Alert.ReadWrite | 'Read and write alerts'
 
 ## HTTP request
 ```