TheMicrosoft Graph API now supports Microsoft Intune with specific APIs and permission roles. The Microsoft Graph API uses Microsoft Entra ID for authentication and access control.Access to the Intune APIs in Microsoft Graph requires:

• An application ID with:

  • Permission to call Microsoft Entra ID and the Microsoft Graph APIs.
  • Permission scopes relevant to the specific application tasks.

• User credentials with:

  • Permission to access the Microsoft Entra tenant associated with the application.
  • Role permissions required to support the application permission scopes.

• The end user to grant permission to the app to perform applications tasks for their Azure tenant.

This article:

• Shows how to register an application with access to the Microsoft Graph API and relevant permission roles.

• Describes the Intune API permission roles.

• Provides Intune API authentication examples for C# and PowerShell.

• Describes how to support multiple tenants.

To learn more, see:

• Authorize access to web applications using OAuth 2.0 and Microsoft Entra ID
• Getting start with Microsoft Entra authentication
• Integrating applications with Microsoft Entra ID
• Understand OAuth 2.0

Register apps to use the Microsoft Graph API

To register an app to use Microsoft Graph API:

1. Sign in to theMicrosoft Entra admin center using administrative credentials.

   As appropriate, you may use:

   • The tenant admin account.
   • A tenant user account with theUsers can register applications setting enabled.

2. In the admin center, expandIdentity >Applications, and then selectApp registrations.

   

3. Either chooseNew registration to create a new application or choose an existing application. (If you choose an existing application, skip the next step.)

4. In theRegister an application pane, specify the following:

   • AName for the application (displayed when users sign in).

   • TheSupported account type.

   • ARedirect URI value.This value is optional.

     Note

     Azure AD Graph API is in its retirement phase. For more information, seeUpdate your applications to use Microsoft Authentication Library (MSAL) and Microsoft Graph API.

     

     To learn more, seeAuthentication Scenarios for Microsoft Entra ID.

5. SelectRegister to add your new application.

   By selectingRegister, you agree to theMicrosoft Platform Policies.

6. From the application pane for your app:

   1. Note theApplication (client) ID value.

   2. Then, from the navigation menu, selectAPI permissions.

7. From theAPI permissions pane:

   1. SelectAdd a permission, and then on theMicrosoft APIs tab, select theMicrosoft Graph tile.

   2. Select theApplication permissions option to show all of the available permissions, and then select the type of permissions your application requires.

   3. Choose the roles required for your app by placing a checkmark to the left of the relevant names. To learn about specific Intune permission scopes, seeIntune permission scopes. To learn about other Graph API permission scopes, seeMicrosoft Graph permissions reference.

   For best results, choose the fewest roles needed to implement your application.

Data warehouse and reporting permissions

When you add an application through the Microsoft Entra admin center, you can choose the Intune API permissions based on the requirements of your application.

• get_data_warehouse - Use this API permission to grant access to the Intune data warehouse API from Microsoft Intune. For more information, seeUsing the Microsoft Intune Data Warehouse.

Partner solution APIs

The following Intune API permissions are available when adding an application through the Microsoft Entra admin center:

• get_device_compliance - This API permission is used to get device state and compliance information from Microsoft Intune. This API permission is used by Network Access Control partners. For more information, seeNetwork Access Control integration with Intune.
• manage_partner_compliance_policy - This API permission is used to manage partner compliance policies with Microsoft Intune. This API permission allows the app to send partner compliance policies and its Microsoft Entra group assignment to Microsoft Intune without a signed-in user. It is used by device compliance partners. For more information, seeThird party device compliance partners.
• pfx_cert_provider - This API permission is used to send PFX certificates to Intune for a specific user. Intune delivers the certificate to all devices enrolled by the user. For more information, seePFX Import Powershell.
• scep_challenge_provider - This API permission is used to send SCEP challenges to Intune for certificate request validation. It is used by Certification Authority partners. For more information, seePartner Certification Authority.
• update_device_attributes - This API permission is used to send device information to Intune from device compliance and mobile threat defense partners. For more information, seeMobile Threat Defense integration with Intune andThird party device compliance partners.
• update_device_health - This API permission is used to send device health and threat status information to Intune from mobile threat defense partners. For more information, seeMobile Threat Defense integration with Intune.

If you are a partner interested in integrating with Intune using these API permissions, contact theMicrosoft Intelligent Security Association] team for information.

When finished, chooseAdd permissions to save your changes.

At this point, you may also:

• Choose to grant permission for all tenant accounts to use the app without providing credentials.

  To do so, you can grant permissions and accept the confirmation prompt.

  When you run the application for the first time, you're prompted to grant the app permission to perform the selected roles.

• Make the app available to users outside your tenant. (This is typically only required for partners supporting multiple tenants/organizations.)

  To do so:

  1. ChooseManifest from the application pane.

     

  2. Change the value of theavailableToOtherTenants setting totrue.

  3. Save your changes.

App listing

If you receive a large amount of data while requesting your app listing when using Graph API, you may encounter a 503 Service Unavailable error. We recommended that you try again with a smaller page size, such as 20 or fewer elements.

Intune permission scopes

Microsoft Entra ID and Microsoft Graph use permission scopes to control access to corporate resources.

Permission scopes (also called theOAuth scopes) control access to specific Intune entities and their properties. This section summarizes the permission scopes for Intune API features.

To learn more:

• Microsoft Entra authentication
• Application permission scopes

When you grant permission to Microsoft Graph, you can specify the following scopes to control access to Intune features:The following table summarizes the Intune API permission scopes. The first column shows the name of the feature as displayed in theMicrosoft Intune admin center and the second column provides the permission scope name.

The table lists the settings as they appear in theMicrosoft Intune admin center. The following sections describe the scopes in alphabetical order.

At this time, all Intune permission scopes require administrator access. This means you need corresponding credentials when running apps or scripts that access Intune API resources.

DeviceManagementApps.Read.All

• Enable Access setting:Read Microsoft Intune apps

• Permits read access to the following entity properties and status:

  • Client Apps
  • Mobile App Categories
  • App Protection Policies
  • App Configurations

DeviceManagementApps.ReadWrite.All

• Enable Access setting:Read and write Microsoft Intune apps

• Allows the same operations asDeviceManagementApps.Read.All

• Also permits changes to the following entities:

  • Client Apps
  • Mobile App Categories
  • App Protection Policies
  • App Configurations

DeviceManagementConfiguration.Read.All

• Enable Access setting:Read Microsoft Intune device configuration and policies

• Permits read access to the following entity properties and status:

  • Device Configuration
  • Device Compliance Policy
  • Notification Messages

DeviceManagementConfiguration.ReadWrite.All

• Enable Access setting:Read and write Microsoft Intune device configuration and policies

• Allows the same operations asDeviceManagementConfiguration.Read.All

• Apps can also create, assign, delete, and change the following entities:

  • Device Configuration
  • Device Compliance Policy
  • Notification Messages

DeviceManagementManagedDevices.PrivilegedOperations.All

• Enable Access setting:Perform user-impacting remote actions on Microsoft Intune devices

• Permits the following remote actions on a managed device:

  • Retire
  • Wipe
  • Reset/Recover Passcode
  • Remote Lock
  • Enable/Disable Lost Mode
  • Clean PC
  • Reboot
  • Delete User from Shared Device

DeviceManagementManagedDevices.Read.All

• Enable Access setting:Read Microsoft Intune devices

• Permits read access to the following entity properties and status:

  • Managed Device
  • Device Category
  • Detected App
  • Remote actions
  • Malware information

DeviceManagementManagedDevices.ReadWrite.All

• Enable Access setting:Read and write Microsoft Intune devices

• Allows the same operations asDeviceManagementManagedDevices.Read.All

• Apps can also create, delete, and change the following entities:

  • Managed Device
  • Device Category

• The following remote actions are also allowed:

  • Locate devices
  • Disable Activation Lock
  • Request remote assistance

DeviceManagementRBAC.Read.All

• Enable Access setting:Read Microsoft Intune RBAC settings

• Permits read access to the following entity properties and status:

  • Role Assignments
  • Role Definitions
  • Resource Operations

DeviceManagementRBAC.ReadWrite.All

• Enable Access setting:Read and write Microsoft Intune RBAC settings

• Allows the same operations asDeviceManagementRBAC.Read.All

• Apps can also create, assign, delete, and change the following entities:

  • Role Assignments
  • Role Definitions

DeviceManagementScripts.Read.All

• Enable Access setting:Read Microsoft Intune scripts

• Apps can view (read) a script, specifically:

  • Device Shell Scripts
  • Device Health Scripts
  • Device Compliance Scripts
  • Device Custom Attribute Shell Scripts
  • Device Management Scripts

DeviceManagementScripts.ReadWrite.All

• Enable Access setting:Read and write Microsoft Intune scripts
  Allows the same operations asDeviceManagementScripts.Read.All

• Apps can create, update or delete a script, specifically:

  • Device Shell Scripts
  • Device Health Scripts
  • Device Compliance Scripts
  • Device Custom Attribute Shell Scripts
  • Device Management Scripts

DeviceManagementServiceConfig.Read.All

• Enable Access setting:Read Microsoft Intune configuration

• Permits read access to the following entity properties and status:

  • Device Enrollment
  • Apple Push Notification Certificate
  • Apple Device Enrollment Program
  • Apple Volume Purchase Program
  • Exchange Connector
  • Terms and Conditions
  • Cloud PKI
  • Branding
  • Mobile Threat Defense

DeviceManagementServiceConfig.ReadWrite.All

• Enable Access setting:Read and write Microsoft Intune configuration

• Allows the same operations as DeviceManagementServiceConfig.Read.All_

• Apps can also configure the following Intune features:

  • Device Enrollment
  • Apple Push Notification Certificate
  • Apple Device Enrollment Program
  • Apple Volume Purchase Program
  • Exchange Connector
  • Terms and Conditions
  • Cloud PKI
  • Branding
  • Mobile Threat Defense

Microsoft Entra authentication examples

This section shows how to incorporate Microsoft Entra ID into your C# and PowerShell projects.

In each example, you'll need to specify an application ID that has at least theDeviceManagementManagedDevices.Read.All permission scope (discussed earlier).

When testing either example, you may receive HTTP status 403 (Forbidden) errors similar to the following:

{  "error": {    "code": "Forbidden",    "message": "Application is not authorized to perform this operation - Operation ID " +       "(for customer support): 00000000-0000-0000-0000-000000000000 - " +       "Activity ID: cc7fa3b3-bb25-420b-bfb2-1498e598ba43 - " +       "Url: https://example.manage.microsoft.com/" +       "Service/Resource/RESTendpoint?" +       "api-version=2017-03-06 - CustomApiErrorPhrase: ",    "innerError": {      "request-id": "00000000-0000-0000-0000-000000000000",      "date": "1980-01-0112:00:00"    }  }}

If this happens, verify that:

• You've updated the application ID to one authorized to use the Microsoft Graph API and theDeviceManagementManagedDevices.Read.All permission scope.

• Your tenant credentials support administrative functions.

• Your code is similar to the displayed samples.

Authenticate Microsoft Entra ID in C#

This example shows how to use C# to retrieve a list of devices associated with your Intune account.

1. Start Visual Studio and then create a new Visual C# Console app (.NET Framework) project.

2. Enter a name for your project and provide other details as desired.

   

3. Use the Solution Explorer to add the Microsoft MSAL NuGet package to the project:

   1. Right-click the Solution Explorer.
   2. ChooseManage NuGet Packages… >Browse.
   3. SelectMicrosoft.Identity.Client and then chooseInstall.

4. Add the following statements to the top ofProgram.cs:

   using Microsoft.Identity.Client;using System.Net.Http;

5. Add a method to create the authorization header:

   private static async Task<string> GetAuthorizationHeader(){    string applicationId = "<Your Application ID>";    string authority = "https://login.microsoftonline.com/common/";    Uri redirectUri = new Uri("urn:ietf:wg:oauth:2.0:oob");    AuthenticationContext context = new AuthenticationContext(authority);    AuthenticationResult result = await context.AcquireTokenAsync(        "https://graph.microsoft.com",        applicationId, redirectUri,        new PlatformParameters(PromptBehavior.Auto));    return result.CreateAuthorizationHeader();

   Remember to change the value ofapplication_ID to match one granted at least theDeviceManagementManagedDevices.Read.All permission scope, as described earlier.

6. Add a method to retrieve the list of devices:

   private static async Task<string> GetMyManagedDevices(){    string authHeader = await GetAuthorizationHeader();    HttpClient graphClient = new HttpClient();    graphClient.DefaultRequestHeaders.Add("Authorization", authHeader);    return await graphClient.GetStringAsync(        "https://graph.microsoft.com/beta/me/managedDevices");}

7. UpdateMain to callGetMyManagedDevices:

   string devices = GetMyManagedDevices().GetAwaiter().GetResult();Console.WriteLine(devices);

8. Compile and run your program.

When you first run your program, you should receive two prompts. The first requests your credentials and the second grants permissions for themanagedDevices request.

For reference, here's the completed program:

using Microsoft.Identity.Client;using System;using System.Net.Http;using System.Threading.Tasks;namespace IntuneGraphExample{    class Program    {        static void Main(string[] args)        {            string devices = GetMyManagedDevices().GetAwaiter().GetResult();            Console.WriteLine(devices);        }        private static async Task<string> GetAuthorizationHeader()        {            string applicationId = "<Your Application ID>";            string authority = "https://login.microsoftonline.com/common/";            Uri redirectUri = new Uri("urn:ietf:wg:oauth:2.0:oob");            AuthenticationContext context = new AuthenticationContext(authority);            AuthenticationResult result = await context.AcquireTokenAsync("https://graph.microsoft.com", applicationId, redirectUri, new PlatformParameters(PromptBehavior.Auto));            return result.CreateAuthorizationHeader();        }        private static async Task<string> GetMyManagedDevices()        {            string authHeader = await GetAuthorizationHeader();            HttpClient graphClient = new HttpClient();            graphClient.DefaultRequestHeaders.Add("Authorization", authHeader);            return await graphClient.GetStringAsync("https://graph.microsoft.com/beta/me/managedDevices");        }    }}

Authenticate Microsoft Entra ID using Microsoft Graph PowerShell

PowerShell scripts can use the Microsoft Graph PowerShell module for authentication. To learn more, seeMicrosoft Graph PowerShell and theIntune PowerShell examples.

Support multiple tenants and partners

If your organization supports organizations with their own Microsoft Entra tenants, you may want to permit your clients to use your application with their respective tenants.

To do so:

1. Verify that the client account exists in the target Microsoft Entra tenant.

2. Verify that your tenant account allows users to register applications (seeUser settings).

3. Establish a relationship between each tenant.

   To do so, either:

   a. Use theMicrosoft Partner Center to define a relationship with your client and their email address.

   b. Invite the user to become a guest of your tenant.

To invite the user to be a guest of your tenant:

1. ChooseAdd a guest user from theQuick tasks panel.

   

2. Enter the client's email address and (optionally) add a personalized message for the invite.

   

3. ChooseInvite.

This sends an invite to the user.

The user needs to choose theGet Started link to accept your invitation.

When the relationship is established (or your invitation has been accepted), add the user account to theDirectory role.

Remember to add the user to other roles as needed. For example, to allow the user to manage Intune settings, they need to be at least anIntune Service administrator.

Also:

• Usehttps://admin.microsoft.com to assign an Intune license to your user account.

• Update application code to authenticate to the client's Microsoft Entra tenant domain, rather than your own.

  For example, suppose your tenant domain iscontosopartner.onmicrosoft.com and your client's tenant domain isnorthwind.onmicrosoft.com, you would update your code to authenticate to your client's tenant.

  To do so in a C# application based on the earlier example, you'd change the value of theauthority variable:

  string authority = "https://login.microsoftonline.com/common/";

  to

  string authority = "https://login.microsoftonline.com/northwind.onmicrosoft.com/";