Which of the following is the process of restricting access to certain material on the Web group of answer choices?

Skip to main content

This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.

Microsoft Graph permissions reference

• Article
• 09/15/2022
• 146 minutes to read

In this article

For your app to access data in Microsoft Graph, the user or administrator must grant it the correct permissions via a consent process. This topic lists the permissions associated with each major set of Microsoft Graph APIs. It also provides guidance about how to use the permissions.

Note

As a best practice, request the least privileged permissions that your app needs in order to access data and function correctly. Requesting permissions with more than the necessary privileges is poor security practice, which may cause users to refrain from consenting and affect your app's usage.

To learn more about how permissions work, see Authentication and authorization basics, and watch the following video.

Microsoft Graph permission names

Microsoft Graph permission names follow a simple pattern: resource.operation.constraint. For example, User.Read grants permission to read the profile of the signed-in user, User.ReadWrite grants permission to read and modify the profile of the signed-in user, and Mail.Send grants permission to send mail on behalf of the signed-in user.

The constraint element of the name determines the potential extent of access your app will have within the directory. Currently Microsoft Graph supports the following constraints:

• All grants permission for the app to perform the operations on all of the resources of the specified type in a directory. For example, User.Read.All potentially grants the app privileges to read the profiles of all of the users in a directory.
• Shared grants permission for the app to perform the operations on resources that other users have shared with the signed-in user. This constraint is mainly used with Outlook resources like mail, calendars, and contacts. For example, Mail.Read.Shared, grants privileges to read mail in the mailbox of the signed-in user as well as mail in mailboxes that other users in the organization have shared with the signed-in user.
• AppFolder grants permission for the app to read and write files in a dedicated folder in OneDrive. This constraint is only exposed on Files permissions and is only valid for Microsoft accounts.
• WhereInstalled grants permission for the app to perform the operations on all the resources where the associated Teams application is installed. For example, Chat.Read.WhereInstalled grants the app privileges to read all chat messages for all chats where the associated Teams application is installed. There is usually a one-to-one mapping between an app (Azure AD application) and a Teams application. The webApplicationInfo section of the Teams app manifest of a Teams app specifies the Azure AD application Id.
• If no constraint is specified the app is limited to performing the operations on the resources owned by the signed-in user. For example, User.Read grants privileges to read the profile of the signed-in user only, and Mail.Read grants permission to read only mail in the mailbox of the signed-in user.

Note

In delegated scenarios, your app's access is also limited by the privileges of the signed-in user. These privileges are determined by the user's assigned roles and their relationship to the data being accessed. For example, if the signed-in user doesn't have the appropriate privileges to view a file, then the client app won't be able to read that file either, even if the app is granted the File.Read.All delegated permission.

Microsoft accounts and work or school accounts

Not all permissions are valid for both Microsoft accounts and work or school accounts. You can check the Microsoft Account Supported column for each permission group to determine whether a specific permission is valid for Microsoft accounts, work or school accounts, or both.

Limits on requested permissions per app

Azure AD limits the number of permissions that can be requested and consented by a client app. These limits depend on the signInAudience value for your app, shown in the app's manifest.

Permissions availability status

Microsoft Graph permissions in the Azure portal are generally available and in GA status for all apps to use, except for a few sets that are in preview or private preview status. Permissions in preview are available to the public; they may change and may not be promoted to GA status. Permissions in private preview status are not and may never become available to the public. Do not use permissions in preview or private preview status in production apps.

User and group search limitations for guest users in organizations

User and group search capabilities allow the app to search for any user or group in an organization's directory by performing queries against the /users or /groups resource set (for example, https://graph.microsoft.com/v1.0/users). Both administrators and users have this capability; however, guest users do not.

Note

Guest users have the same access that members enabled under External Identities > External Collaboration Settings > Guest user access have. The users API works with guest tokens as well.

If the signed-in user is a guest user, depending on the permissions an app has been granted, it can read the profile of a specific user or group (for example, https://graph.microsoft.com/v1.0/users/241f22af-f634-44c0-9a15-c8cd2cea5531); however, it cannot perform queries against the /users or /groups resource set that potentially return more than a single resource.

With the appropriate permissions, the app can read the profiles of users or groups that it obtains by following links in navigation properties; for example, /users/{id}/directReports or /groups/{id}/members.

Limited information returned for inaccessible member objects

Container objects such as groups support members of various types, for example users and devices. When an application queries the membership of a container object and does not have permission to read a certain type, members of that type are returned but with limited information. The application receives a 200 response and a collection of objects. Complete information is returned for the object types that the application has permissions to read. For the object types which the application does not have permission to read, only the the object type and ID are returned.

This is applied to all relationships that are of directoryObject type (not just member links). Examples include /groups/{id}/members, /users/{id}/memberOf or me/ownedObjects.

For example, let's say an application has User.Read.All and Group.Read.All permissions for Microsoft Graph. A group has been created and that group contains a user, a group, and a device. The application calls list group members. The application has access to the user and group objects in the group, but not the device object. In the response, all the selected properties of the user and group objects are returned. For the device object, however, only limited information is returned. The data type and object ID are returned for the device, but all other properties have a value of null. Apps without permission will not be able to use the ID to get the actual object.

GET https://graph.microsoft.com/v1.0/groups/{id}/members?$select=id,displayName,description,createdDateTime,deletedDateTime,homepage,loginUrl HTTP/1.1

The following is the JSON response:

{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#directoryObjects(id,displayName,description,createdDateTime,deletedDateTime,homepage,loginUrl)",
    "value":[
        {
            "@odata.type":"#microsoft.graph.user",
            "id":"69d035a3-29c9-469f-809d-d21a4ae69e65",
            "displayName":"Jane Dane",
            "createdDateTime":"2019-09-18T09:06:51Z",
            "deletedDateTime":null
        },
        {
            "@odata.type":"#microsoft.graph.group",
            "id":"c43a7cc9-2d95-44b6-bf6a-6392e41949b4",
            "displayName":"Group 1",
            "description":null,
            "createdDateTime":"2019-10-24T01:34:35Z",
            "deletedDateTime":null
        },
        {
            "@odata.type":"#microsoft.graph.device",
            "id": "d282309e-f91d-43b6-badb-9e68aa4b4fc8",
            "accountEnabled":null,
            "deviceId":null,
            "displayName":null,
            "operatingSystem":null,
            "operatingSystemVersion":null
        }
    ]
}

Access reviews permissions

Delegated permissions

Application permissions

Remarks

AccessReview.Read.All, AccessReview.ReadWrite.All, AccessReview.ReadWrite.Membership are valid only for work or school accounts.

For an app with delegated permissions to read access reviews of a group or app, the signed-in user must be a member of one of the following administrator roles: Global Administrator, Security Administrator, Security Reader or User Administrator. For an app with delegated permissions to write access reviews of a group or app, the signed-in user must be a member of one of the following administrator roles: Global Administrator or User Administrator.

For an app with delegated permissions to read access reviews of an Azure AD role, the signed-in user must be a member of one of the following administrator roles: Global Administrator, Security Administrator, Security Reader or Privileged Role Administrator. For an app with delegated permissions to write access reviews of an Azure AD role, the signed-in user must be a member of one of the following administrator roles: Global Administrator or Privileged Role Administrator.

For more information about administrator roles, see Assigning administrator roles in Azure Active Directory.

Administrative units permissions

Delegated permissions

Application permissions

Remarks

With the AdministrativeUnit.Read.All permission an application can read administrative unit information including members.

With the AdministrativeUnit.ReadWrite.All permission an application can create, read, update, and delete administrative unit information including members.

AdministrativeUnit.Read.All and AdministrativeUnit.ReadWrite.All are valid only for work or school accounts.

Example usage

Note

The v1.0 endpoint for the administrative units API is /v1.0/directory/administrativeUnits.

• AdministrativeUnit.Read.All: Read administrative units (GET /beta/administrativeUnits)
• AdministrativeUnit.Read.All: Read members list of an administrative unit (GET /beta/administrativeUnits/<id>/members)
• AdministrativeUnit.ReadWrite.All: Create an administrative unit (POST /beta/administrativeUnits)
• AdministrativeUnit.ReadWrite.All: Update an administrative unit (PATCH /beta/administrativeUnits/<id>)
• AdministrativeUnit.ReadWrite.All: Add members to an administrative unit (POST /beta/administrativeUnits/<id>/members)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Analytics resource permissions

Delegated permissions

Application permissions

None.

Example usage

Delegated

• Analytics.Read: List related settings for a user (GET /beta/me/analytics/settings)

Application

None.

AppCatalog resource permissions

Delegated permissions

Application permissions

Remarks

Currently the only catalog is the list of applications in Microsoft Teams.

Example usage

Delegated

• AppCatalog.ReadWrite.All: List all applications in catalog (GET /beta/appCatalogs/teamsApps)
• AppCatalog.ReadWrite.All: Publish an app (POST /beta/appCatalogs/teamsApps)
• AppCatalog.ReadWrite.All: Update a published app (PATCH /beta/appCatalogs/teamsApps/{id})
• AppCatalog.ReadWrite.All: Remove a published app (DELETE /beta/appCatalogs/teamsApps/{id})

Application

None.

Application resource permissions

Delegated permissions

Application permissions

Remarks

Caution

Permissions that allow granting authorization, such as AppRoleAssignment.ReadWrite.All, allow an application to grant additional privileges to itself, other applications, or any user. Likewise, permissions that allow managing credentials, such as Application.ReadWrite.All, allow an application to act as other entities, and use the privileges they were granted. Use caution when granting any of these permissions.

The Application.ReadWrite.OwnedBy permission allows the same operations as Application.ReadWrite.All except that the former allows these operations only on applications and service principals that the calling app is an owner of. Ownership is indicated by the owners navigation property on the target application or service principal resource.

NOTE: Using the Application.ReadWrite.OwnedBy permission to call GET /applications to list applications will fail with a 403. Instead use GET servicePrincipals/{id}/ownedObjects to list the applications owned by the calling application.

Example usage

Delegated

• Application.Read.All: List all applications (GET /v1.0/applications)
• Application.ReadWrite.All: Update a service principal (PATCH /v1.0/servicePrincipals/{id})

Application

• Application.Read.All: List all applications (GET /v1.0/applications)

• Application.ReadWrite.All: Delete a service principal (DELETE /v1.0/servicePrincipals/{id})

• Application.ReadWrite.OwnedBy: Create an application (POST /v1.0/applications)

• Application.ReadWrite.OwnedBy: List all applications owned by the calling application (GET /v1.0/servicePrincipals/{id}/ownedObjects)

• Application.ReadWrite.OwnedBy: Add another owner to an owned application (POST /v1.0/applications/{id}/owners/$ref).

  NOTE: This may require additional permissions.

Audit log permissions

Delegated permissions

Application permissions

BitLocker recovery key permissions

Delegated permissions

Application permissions

None.

Example usage

Delegated

• BitlockerKey.ReadBasic.All: List the BitLocker recovery keys for all devices in the tenant without returning the 'key' property (GET /bitlocker/recoveryKeys).
• BitlockerKey.Read.All: Get a BitLocker recovery key with the recovery key (GET /bitlocker/recoveryKeys/{bitlockerRecoveryKeyId}?$select=key)

Bookings permissions

Delegated permissions

Application permissions

Example usage

Delegated

• Bookings.Read.All: Get the ID and names of the collection of Bookings businesses that has been created for a tenant (GET /bookingBusinesses).
• BookingsAppointment.ReadWrite.All: Create an appointment for a service at a Bookings business (POST /bookingBusinesses/{id}/appointments).
• Bookings.ReadWrite.All: Create a new service for the specified Bookings business (POST /bookingBusinesses/{id}/services).
• Bookings.Manage.All: Make the scheduling page of this business available to external customers (POST /bookingBusinesses/{id}/publish).

Calendars permissions

Delegated permissions

Application permissions

Important Administrators can configure application access policy to limit app access to specific mailboxes and not to all the mailboxes in the organization, even if the app has been granted the application permissions of Calendars.Read or Calendars.ReadWrite.

Example usage

Delegated

• Calendars.Read: Get events on the user's calendar between April 23, 2017 and April 29, 2017 (GET /me/calendarView?startDateTime=2017-04-23T00:00:00&endDateTime=2017-04-29T00:00:00).
• Calendars.Read.Shared: Find meeting times where all attendees are available (POST /users/{id|userPrincipalName}/findMeetingTimes).
• Calendars.ReadWrite: Add an event to the user's calendar (POST /me/events).

Application

• Calendars.Read: Find events in a conference room's calendar organized by (GET /users/{id | userPrincipalName}/events?$filter=organizer/emailAddress/address eq '').
• Calendars.Read: List all events on a user's calendar for the month of May (GET /users/{id | userPrincipalName}/calendarView?startDateTime=2017-05-01T00:00:00&endDateTime=2017-06-01T00:00:00)
• Calendars.ReadWrite: Add an event to a user's calendar for approved time off (POST /users/{id | userPrincipalName}/events).

For more complex scenarios involving multiple permissions, see Permission scenarios.

Calls permissions

Delegated permissions

None.

Application permissions

*Important: You may NOT use the Cloud Communications APIs to record or otherwise persist media content from calls or meetings that your application accesses, or data derived from that media content. Make sure that you are compliant with the laws and regulations in your area regarding data protection and confidentiality of communications. Please see the Terms of Use and consult with your legal counsel for more information.

Example usage

Application

• Calls.Initiate.All: Make a peer-to-peer call from the application to a user in the organization (POST /beta/communications/calls).
• Calls.InitiateGroupCall.All: Make a group call from the application to a group of users in the organization (POST /beta/communications/calls).
• Calls.JoinGroupCall.All: Join a group call or online meeting from the application (POST /beta/communications/calls).
• Calls.JoinGroupCallasGuest.All: Join a group call or online meeting from the application, but the application only has guest privileges in the meeting (POST /beta/communications/calls).
• Calls.AccessMedia.All: Create or join a call and the app gets direct access to participant media streams in the call (POST /beta/communications/calls).

Note: For request examples, see Create call.

For more complex scenarios involving multiple permissions, see Permission scenarios.

Call records permissions

Delegated permissions

None.

Application permissions

Remarks

The CallRecords.Read.All permission grants an application privileged access to callRecords for every call and online meeting within your organization, including calls to and from external phone numbers. This includes potentially sensitive details about who participated in the call, as well as technical information pertaining to these calls and meetings that can be used for network troubleshooting, such as IP addresses, device details, and other network information.

The CallRecord-PstnCalls.Read.All permission grants an application access to PSTN (calling plans) and direct routing call logs. This includes potentially sensitive information about users as well as calls to and from external phone numbers.

Important: Discretion should be used when granting these permissions to applications. Call records can provide insights into the operation of your business, and so can be a target for malicious actors. Only grant these permissions to applications you trust to meet your data protection requirements.

Important: Make sure that you are compliant with the laws and regulations in your area regarding data protection and confidentiality of communications. Please see the Terms of Use and consult with your legal counsel for more information.

Example usage

Application

• CallRecords.Read.All: Retrieve a call record (GET /v1.0/communications/callRecords/{id}).
• CallRecords.Read.All: Subscribe to new call records (POST /v1.0/subscriptions).
• CallRecords.Read.All: Retrieve direct routing call records within the specified time range (GET /v1.0/communications/callRecords/microsoft.graph.callRecords.getDirectRoutingCalls(fromDateTime={start date and time),toDateTime={end date and time)))
• CallRecord-PstnCalls.Read.All: Retrieve PSTN call records within the specified time range (GET /v1.0/communications/callRecords/microsoft.graph.callRecords.getPstnCalls(fromDateTime={start date and time),toDateTime={end date and time)))

For more complex scenarios involving multiple permissions, see Permission scenarios.

Channel permissions

Delegated permissions

Application permissions

Channel member permissions

Delegated permissions

Application permissions

Channel message permissions

Delegated permissions

Application permissions

Note: See also Group.Read.All.

Channel settings permissions

Delegated permissions

Application permissions

Chat permissions

Delegated permissions

Application permissions

Note: For messages in a channel, see ChannelMessage permissions.

Chat membership permissions

Delegated permissions

Application permissions

Chat resource-specific consent permissions

Application permissions

Note

Currently, these permissions are supported only in the beta version of Microsoft Graph.

ChatMessage permissions

Delegated permissions

Cloud PC permissions

Delegated permissions

Application permissions

Example usage

Delegated

• CloudPC.Read.All: View the properties of all Cloud PCs (GET /deviceManagement/virtualEndpoint/cloudPCs).
• CloudPC.ReadWrite.All: Edit the Cloud PC provisioning policy (PATCH /deviceManagement/virtualEndpoint/provisioningPolicies/{id}).

Application

• CloudPC.Read.All: View the properties of all Cloud PCs (GET /deviceManagement/virtualEndpoint/cloudPCs).
• CloudPC.ReadWrite.All: Edit the Cloud PC provisioning policy (PATCH /deviceManagement/virtualEndpoint/provisioningPolicies/{id}).

Consent requests permissions

Delegated permissions

Application permissions

Delegated permissions

Application permissions

Important Administrators can configure application access policy to limit app access to specific mailboxes and not all the mailboxes in the organization, even if the app has been granted the application permissions of Contacts.Read or Contacts.ReadWrite.

Example usage

Delegated

• Contacts.Read: Read a contact from one of the top-level contact folders of the signed-in user (GET /me/contactfolders/{Id}/contacts/{id}).
• Contacts.ReadWrite: Update the contact photo of one of the signed-in user's contacts (PUT /me/contactfolders/{contactFolderId}/contacts/{id}/photo/$value).
• Contacts.ReadWrite: Add contacts to the root folder of the signed-in user (POST /me/contacts).

Application

• Contacts.Read: Read contacts from one of the top-level contact folders of any user in the organization (GET /users/{id | userPrincipalName}/contactfolders/{Id}/contacts/{id}).
• Contacts.ReadWrite: Update the photo for any contact of any user in an organization (PUT /users/{id | userPrincipalName}/contactfolders/{contactFolderId}/contacts/{id}/photo/$value).
• Contacts.ReadWrite: Add contacts to the root folder of any user in the organization (POST /users/{id | userPrincipalName}/contacts).

For more complex scenarios involving multiple permissions, see Permission scenarios.

Custom security attributes permissions

Delegated permissions

Application permissions

Granular delegated admin privileges (GDAP) permissions

Delegated permissions

Application permissions

Device permissions

Delegated permissions

Application permissions

Note

Before December 3rd, 2020, when the application permission Device.ReadWrite.All was granted, the Device Managers directory role was also assigned to the app's service principal. This directory role assignment is not removed automatically when the associated application permissions is revoked. To ensure that an application's access to read or write to devices is removed, customers must also remove any related directory roles that were granted to the application.

A service update disabling this behavior began rolling out on December 3rd, 2020. Deployment to all customers completed on January 11th, 2021. Directory roles are no longer automatically assigned when application permissions are granted.

Example usage

Application

• Device.ReadWrite.All: Read all registered devices in the organization (GET /devices).

For more complex scenarios involving multiple permissions, see Permission scenarios.

Directory permissions

Delegated permissions

Application permissions

Remarks

Directory permissions provide the highest level of privilege for accessing directory resources such as user, group, and device in an organization.

They also exclusively control access to other directory resources like: organizational contacts, schema extension APIs, Privileged Identity Management (PIM) APIs, as well as many of the resources and APIs listed under the Azure Active Directory node in the v1.0 and beta API reference documentation. These include administrative units, directory roles, directory settings, policy, and many more.

Note

Before December 3rd, 2020, when the application permission Directory.Read.All was granted, the Directory Readers directory role was also assigned to the app's service principal. When Directory.ReadWrite.All was granted, the Directory Writers directory role was also assigned. These directory roles are not removed automatically when the associated application permissions are revoked. To remove an application's access to read or write to the directory, customers must also remove any directory roles that were granted to the application.

A service update disabling this behavior began rolling out on December 3rd, 2020. Deployment to all customers completed on January 11th, 2021. Directory roles are no longer automatically assigned when application permissions are granted.

The Directory.ReadWrite.All permission grants the following privileges:

• Full read of all directory resources (both declared properties and navigation properties)
• Create and update users
• Disable and enable users (but not Company Administrator)
• Set user alternative security ID (but not administrators)
• Create and update groups
• Manage group memberships
• Update group owner
• Manage license assignments
• Define schema extensions on applications
• Manage directory settings
• Manage admin consent workflow configuration (but not whether admin consent is required or who is authorized to grant admin consent)

Note:

• No rights to reset user passwords.
• Updating another user's businessPhones, mobilePhone, or otherMails property is only allowed on users who are non-administrators or assigned one of the following roles: Directory Readers, Guest Inviter, Message Center Reader and Reports Reader. For more details, see Helpdesk (Password) Administrator in Azure AD available roles. This is the case for apps granted either the User.ReadWrite.All or Directory.ReadWrite.All delegated or application permissions.
• No rights to delete resources (including users or groups).
• Specifically excludes create or update for resources not listed above. This includes: application, oAauth2Permissiongrant, appRoleAssignment, device, servicePrincipal, organization, domains, and so on.

Example usage

Delegated

• Directory.Read.All: List all administrative units in an organization (GET /beta/administrativeUnits)
• Directory.ReadWrite.All: Add members to a directory role (POST /directoryRoles/{id}/members/$ref)

Application

• Directory.Read.All: List all memberships of a user, including directory roles and administrative units (GET /beta/users/{id}/memberOf)
• Directory.Read.All: List all group members, including service principals (GET /beta/groups/{id}/members)
• Directory.ReadWrite.All: Add an owner to a group (POST /groups/{id}/owners/$ref)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Domain permissions

Delegated permissions

Application permissions

eDiscovery permissions

Delegated permissions

Application permissions

None

Example usage

Delegated

• eDiscovery.Read.All: Get the list of cases available to the user (GET /compliance/ediscovery/cases)
• eDiscovery.ReadWrite.All: Create a reviewset query in a review set (POST /compliance/ediscovery/cases/{caseId}/reviewSets/{reviewSetId}/queries)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Education permissions

Delegated permissions

Application permissions

Example usage

Delegated

• EduAssignments.Read: Get the signed-in student's assignment information (GET /education/classes/{id}/assignments/{id})
• EduAssignments.ReadWriteBasic: Submit signed-in student assignment (GET /education/classes/{id}/assignments/{id}submit)
• EduRoster.ReadBasic: Classes a signed-in user attends or teaches (GET /education/classes/{id}/members)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Employee learning permissions

Delegated permissions

Application permissions

Entitlement management permissions

Delegated permissions

Application permissions

Files permissions

Delegated permissions

Application permissions

Remarks

Note: For personal accounts, Files.Read and Files.ReadWrite also grant access to files shared with the signed-in user.

The Files.Read.Selected and Files.ReadWrite.Selected delegated permissions are only valid on work or school accounts and are only exposed for working with Office 365 file handlers (v1.0). They should not be used for directly calling Microsoft Graph APIs.

The Files.ReadWrite.AppFolder delegated permission is only valid for personal accounts and is used for accessing the App Root special folder with the OneDrive Get special folder Microsoft Graph API.

Example usage

Delegated

• Files.Read: Read files stored in the signed-in user's OneDrive (GET /me/drive/root/children)
• Files.Read.All: Read files shared with the signed-in user (GET /me/drive/root/sharedWithMe)
• Files.ReadWrite: Write a file in the signed-in user's OneDrive (PUT /me/drive/root/children/filename.txt/content)
• Files.ReadWrite.All: Write a file shared with the user (PUT /users//drive/root/children/file.txt/content)
• Files.ReadWrite.AppFolder: Write files into the app's folder in OneDrive (PUT /me/drive/special/approot/children/file.txt/content)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Financials permissions

Delegated permissions

Group permissions

Delegated permissions

Application permissions

Remarks

Group functionality is not supported on personal Microsoft accounts.

For Microsoft 365 groups, Group permissions grant the app access to the contents of the group; for example, conversations, files, notes, and so on.

For application permissions, there are some limitations for the APIs that are supported. For more information, see known issues.

In some cases, an app may need Directory permissions to read some group properties like member and memberOf. For example, if a group has a one or more servicePrincipals as members, the app will need effective permissions to read service principals through being granted one of the Directory.* permissions, otherwise Microsoft Graph will return an error. (In the case of delegated permissions, the signed-in user will also need sufficient privileges in the organization to read service principals.) The same guidance applies for the memberOf property, which can return administrativeUnits.

To set a Microsoft 365 group's preferredDataLocation attribute, an app needs Directory.ReadWrite.All permission. When users in a multi-geo environment create a Microsoft 365 group, the preferredDataLocation value for the group is automatically set to that of the user. For more information about groups' preferred data location, see Create a Microsoft 365 group with a specific PDL.

Group permissions are used to control access to Microsoft Teams resources and APIs. Personal Microsoft accounts are not supported.

Group permissions are also used to control access to Microsoft Planner resources and APIs. Only delegated permissions are supported for Microsoft Planner APIs; application permissions are not supported. Personal Microsoft accounts are not supported.

Example usage

Delegated

• Group.Read.All: Read all Microsoft 365 groups that the signed-in user is a member of (GET /me/memberOf/$/microsoft.graph.group?$filter=groupTypes/any(a:a%20eq%20'unified')).
• Group.Read.All: Read all Microsoft 365 group content like conversations (GET /groups/{id}/conversations).
• Group.ReadWrite.All: Update group properties, like photo (PUT /groups/{id}/photo/$value).
• GroupMember.ReadWrite.All: Update group members (POST /groups/{id}/members/$ref).

Note:: This also requires User.ReadBasic.All to read the user to add as a member.

Application

• Group.Read.All: Find all groups with name that starts with 'Sales' (GET /groups?$filter=startswith(displayName,'Sales')).
• Group.ReadWrite.All: Daemon service creates new events on a Microsoft 365 group's calendar (POST /groups/{id}/events).
• Group.Create: Creates a new group (POST /groups).

For more complex scenarios involving multiple permissions, see Permission scenarios.

Identity provider permissions

Delegated permissions

Remarks

IdentityProvider.Read.All and IdentityProvider.ReadWrite.All are valid only for work or school accounts. For an app to read or write identity providers with delegated permissions, the signed-in user must be assigned the Global Administrator role. For more information about administrator roles, see Assigning administrator roles in Azure Active Directory.

Example usage

Delegated

The following usages are valid for both delegated permissions:

• IdentityProvider.Read.All: Read all identity providers configured in the tenant (GET /beta/identityProviders)
• IdentityProvider.Read.All: Read an existing identity provider (GET /beta/identityProviders/{id})
• IdentityProvider.ReadWrite.All Create an identity provider (POST /beta/identityProviders)
• IdentityProvider.ReadWrite.All Update an existing identity provider (PATCH /beta/identityProviders/{id})
• IdentityProvider.ReadWrite.All Delete an existing identity provider (DELETE /beta/identityProviders/{id})

For more complex scenarios involving multiple permissions, see Permission scenarios.

Identity protection risk permissions

Delegated permissions

Application permissions

All identity risk permissions are valid only for work or school accounts. For an app with delegated permissions to read identity risk information, the signed-in user must be a member of one of the following Azure AD administrator roles: Global Administrator, Security Administrator, or Security Reader.

Example usage

The following usages are valid for both delegated and application permissions:

Read risk events

• Read all risk events generated for all users in the tenant (GET /identityProtection/riskDetections)
• Read most recent 50 risk events (GET /identityProtection/riskDetections?$orderBy=detectedDateTime desc&top=50)

Read risky users

• Read all risky users and properties in the tenant (GET /identityProtection/riskyUsers)
• Read all risky users whose aggregate risk level is Medium (GET /identityProtection/riskyUsers?$filter=riskLevel eq 'medium')
• Read the risk information for a specific user (GET /identityProtection/riskyUsers?$filter=id eq 'userId')

Read risky service principals

• Read all risky service principals and properties in the tenant (GET /identityProtection/riskyServicePrincipals)
• Read all risky service principals whose aggregate risk level is Medium (GET /identityProtection/riskyServicePrincipals?$filter=riskLevel eq 'medium')
• Read the risk information for a specific service principal (GET /identityProtection/riskyServicePrincipals?$filter=id eq '{riskyServicePrincipalsId}')

For more complex scenarios involving multiple permissions, see Permission scenarios.

Identity user flow permissions

Delegated permissions

Application permissions

Remarks

IdentityUserFlow.Read.All and IdentityUserFlow.ReadWrite.ALL is valid only for work or school accounts.

For an app with delegated permissions to read user flows, the signed-in user must be a member of one of the following administrator roles: Global Administrator, External Identities User Flow Administrator, or Global Reader. For an app with delegated permissions to write user flows, the signed-in user must be a member of one of the following administrator roles: Global Administrator or External Identities User Flow Administrator.

For more information about administrator roles, see Assigning administrator roles in Azure Active Directory.

Example usage

Delegated and Application

The following usages are valid for both delegated and application permissions:

• IdentityUserFlow.Read.All: Read all user flows in an Azure AD B2C tenant (GET beta/identity/b2cUserFlows)
• IdentityUserFlow.Read.All: Read all user flows in an Azure Active Directory (Azure AD) tenant (GET beta/identity/b2xUserFlows)
• IdentityUserFlow.Read.All: Read all user attribute assignments in an Azure AD B2C user flow (GET beta/identity/b2cUserFlows/{id}/userAttributeAssignments)
• IdentityUserFlow.ReadWrite.All: Create a new user flow in an Azure AD B2C tenant (POST beta/identity/b2cUserFlows)
• IdentityUserFlow.ReadWrite.All: Create a new user flow in an Azure Active Directory (Azure AD) tenant (POST beta/identity/b2xUserflows)
• IdentitytUserFlow.ReadWrite.All: Add an identity provider to an Azure AD B2C user flow (PATCH beta/identity/b2cUserFlows/{id}/identityProviders/$ref)
• IdentityUserFlow.ReadWrite.All: Remove an identity provider from an Azure AD B2C user flow (DELETE beta/identity/b2cUserFlows/{id}/identityProviders/{id})
• IdentityUserFlow.ReadWrite.All: Create a user attribute assignment in an Azure AD B2C user flow (POST beta/identity/b2cUserFlows/{id}/userAttributeAssignments)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Incidents permissions

Delegated permissions

Application permissions

Remarks

Incidents permissions are valid only on work or school accounts.

Example usage

Delegated

• SecurityIncident.Read.All: Read all incidents in an organization that the user is allowed to read (GET /security/incidents)
• SecurityIncident.ReadWrite.All: Read and write to all incidents in an organization that the user is allowed to read and write (GET /security/incidents)

Application

• SecurityIncident.Read.All: Read all incidents in an organization (GET /security/incidents)
• SecurityIncident.ReadWrite.All: Read and write to all incidents in an organization (GET /security/incidents)

Information protection policy permissions

Delegated permissions

Application permissions

Intune device management permissions

Delegated permissions

Application permissions

Remarks

Note: Using the Microsoft Graph APIs to configure Intune controls and policies still requires that the Intune service is correctly licensed by the customer.

These permissions are only valid for work or school accounts.

Example usage

Delegated

• DeviceManagementServiceConfiguration.Read.All: Check the current state of the Intune subscription (GET /deviceManagement/subscriptionState).
• DeviceManagementServiceConfiguration.ReadWrite.All: Create new Terms and Conditions (POST /deviceManagement/termsAndConditions).
• DeviceManagementConfiguration.Read.All: Find the status of a device configuration (GET /deviceManagement/deviceConfigurations/{id}/deviceStatuses).
• DeviceManagementConfiguration.ReadWrite.All: Assign a device compliance policy to a group (POST deviceCompliancePolicies/{id}/assign).
• DeviceManagementApps.Read.All: Find all the Windows Store apps published to Intune (GET /deviceAppManagement/mobileApps?$filter=isOf('microsoft.graph.windowsStoreApp')).
• DeviceManagementApps.ReadWrite.All: Publish a new application (POST /deviceAppManagement/mobileApps).
• DeviceManagementRBAC.Read.All: Find a role assignment by name (GET /deviceManagement/roleAssignments?$filter=displayName eq 'My Role Assignment').
• DeviceManagementRBAC.ReadWrite.All: Create a new custom role (POST /deviceManagement/roleDefinitions).
• DeviceManagementManagedDevices.Read.All: Find a managed device by name (GET /managedDevices/?$filter=deviceName eq 'My Device').
• DeviceManagementManagedDevices.ReadWrite.All: Remove a managed device (DELETE /managedDevices/{id}).
• DeviceManagementManagedDevices.PrivilegedOperations.All: Reset the passcode on a user's managed device (POST /managedDevices/{id}/resetPasscode).

Application

• DeviceManagementServiceConfiguration.Read.All: Check the current state of the Intune subscription (GET /deviceManagement/subscriptionState).
• DeviceManagementServiceConfiguration.ReadWrite.All: Create new Terms and Conditions (POST /deviceManagement/termsAndConditions).
• DeviceManagementConfiguration.Read.All: Find the status of a device configuration (GET /deviceManagement/deviceConfigurations/{id}/deviceStatuses).
• DeviceManagementConfiguration.ReadWrite.All: Assign a device compliance policy to a group (POST deviceCompliancePolicies/{id}/assign).
• DeviceManagementApps.Read.All: Find all the Windows Store apps published to Intune (GET /deviceAppManagement/mobileApps?$filter=isOf('microsoft.graph.windowsStoreApp')).
• DeviceManagementApps.ReadWrite.All: Publish a new application (POST /deviceAppManagement/mobileApps).
• DeviceManagementRBAC.Read.All: Find a role assignment by name (GET /deviceManagement/roleAssignments?$filter=displayName eq 'My Role Assignment').
• DeviceManagementRBAC.ReadWrite.All: Create a new custom role (POST /deviceManagement/roleDefinitions).
• DeviceManagementManagedDevices.Read.All: Find a managed device by name (GET /managedDevices/?$filter=deviceName eq 'My Device').
• DeviceManagementManagedDevices.ReadWrite.All: Remove a managed device (DELETE /managedDevices/{id}).
• DeviceManagementManagedDevices.PrivilegedOperations.All: Reset the passcode on a user's managed device (POST /managedDevices/{id}/resetPasscode).

For more complex scenarios involving multiple permissions, see Permission scenarios.

Lifecycle workflows permissions

Delegated permissions

Application permissions

Mail permissions

Delegated permissions

Application permissions

Important Administrators can configure application access policy to limit app access to specific mailboxes and not to all the mailboxes in the organization, even if the app has been granted the application permissions of Mail.Read, Mail.ReadWrite, Mail.Send, MailboxSettings.Read, or MailboxSettings.ReadWrite.

Remarks

Mail.Read.Shared, Mail.ReadWrite.Shared, and Mail.Send.Shared are only valid for work or school accounts. All other permissions are valid for both Microsoft accounts and work or school accounts.

With the Mail.Send or Mail.Send.Shared permission, an app can send mail and save a copy to the user's Sent Items folder, even if the app does not use a corresponding Mail.ReadWrite or Mail.ReadWrite.Shared permission.

Example usage

Delegated

• Mail.Read: List messages in the user's inbox, sorted by receivedDateTime (GET /me/mailfolders/inbox/messages?$orderby=receivedDateTime DESC).
• Mail.Read.Shared: Find all messages with attachments in a user's inbox that has shared their inbox with the signed-in user (GET /users{id | userPrincipalName}/mailfolders/inbox/messages?$filter=hasAttachments eq true).
• Mail.ReadWrite: Mark a message read (PATCH /me/messages/{id}).
• Mail.Send: Send a message (POST /me/sendmail).
• MailboxSettings.ReadWrite: Update the user's automatic reply (PATCH /me/mailboxSettings).

Application

• Mail.Read: Find messages from (GET /users/{id | userPrincipalName}/messages?$filter=from/emailAddress/address eq '').
• Mail.ReadWrite: Create a new folder in the Inbox named Expense Reports (POST /users/{id | userPrincipalName}/mailfolders).
• Mail.Send: Send a message (POST /users/{id | userPrincipalName}/sendmail).
• MailboxSettings.Read: Get the default timezone for the user's mailbox (GET /users/{id | userPrincipalName}/mailboxSettings/timeZone)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Managed tenant permissions

Delegated permissions

Application permissions

None.

Member permissions

Delegated permissions

Application permissions

Remarks

Member.Read.Hidden is valid only on work or school accounts.

Membership in some Microsoft 365 groups can be hidden. This means that only the members of the group can view its members. This feature can be used to help comply with regulations that require an organization to hide group membership from outsiders (for example, a Microsoft 365 group that represents students enrolled in a class).

Example usage

Delegated

• Member.Read.Hidden: Read the members of an administrative unit with hidden membership on behalf of the signed-in user (GET /administrativeUnits/{id}/members).
• Member.Read.Hidden: Read the members of a group with hidden membership on behalf of the signed-in user (GET /groups/{id}/members).

Application

• Member.Read.Hidden: Read the members of an administrative unit with hidden membership (GET /administrativeUnits/{id}/members).
• Member.Read.Hidden: Read the members of a group with hidden membership (GET /groups/{id}/members).

For more complex scenarios involving multiple permissions, see Permission scenarios.

Notes permissions

Delegated permissions

Application permissions

Remarks

Notes.Read.All and Notes.ReadWrite.All are only valid for work or school accounts. All other permissions are valid for both Microsoft accounts and work or school accounts.

With the Notes.Create permission, an app can view the OneNote notebook hierarchy of the signed-in user and create OneNote content (notebooks, section groups, sections, pages, etc.).

Notes.ReadWrite and Notes.ReadWrite.All also allow the app to modify the permissions on the OneNote content that can be accessed by the signed-in user.

For work or school accounts, Notes.Read.All and Notes.ReadWrite.All allow the app to access other users' OneNote content that the signed-in user has permission to within the organization.

Example usage

Delegated

• Notes.Create: Create a new notebooks for the signed-in user (POST /me/onenote/notebooks).
• Notes.Read: Read the notebooks for the signed-in user (GET /me/onenote/notebooks).
• Notes.Read.All: Get all notebooks that the signed-in user has access to within the organization (GET /me/onenote/notebooks?includesharednotebooks=true).
• Notes.ReadWrite: Update the page of the signed-in user (PATCH /me/onenote/pages/{id}/$value).
• Notes.ReadWrite.All: Create a page in another user's notebook that the signed-in user has access to within the organization (POST /users/{id}/onenote/pages).

Application

• Notes.Read.All: Read all users notebooks in a group (GET /groups/{id}/onenote/notebooks).
• Notes.ReadWrite.All: Update the page in a notebook for any user in the organization (PATCH /users/{id}/onenote/pages/{id}/$value).

For more complex scenarios involving multiple permissions, see Permission scenarios.

Notifications permissions

Delegated permissions

Remarks

Notifications.ReadWrite.CreatedByApp is valid for both Microsoft accounts and work or school accounts. The CreatedByApp constraint associated with this permission indicates that the service will apply implicit filtering to results based on the identity of the calling app, either the Microsoft account app ID or a set of app IDs configured for a cross-platform application identity.

Example usage

Delegated

• Notifications.ReadWrite.CreatedByApp: Publish a user-centric notification, which might then be delivered to the user’s multiple application clients running on different endpoints. (POST /me/notifications/).

Online meetings permissions

Delegated permissions

Application permissions

Important Administrators can configure application access policy to allow apps to access online meetings on behalf of a user.

Example usage

Delegated

• OnlineMeetings.Read: Retrieve the properties and relationships of an online meeting (GET /beta/communications/onlinemeetings/{default id}).
• OnlineMeetings.ReadWrite: Create an online meeting (POST /beta/communications/onlinemeetings).

Application

• OnlineMeetings.Read.All
  • Retrieve the properties and relationships of an online meeting (GET /beta/communications/onlinemeetings/?$filter=VideoTeleconferenceId%20eq%20'{id}').
  • Retrieve an online meeting on behalf of a user (`GET /beta/users/{userId}/onlineMeetings/{id})
• OnlineMeetings.ReadWrite.All
  • Create an online meeting on behalf of a user (`POST /beta/users/{userId}/onlineMeetings/)
  • Update an online meeting on behalf of a user (`PATCH /beta/users/{userId}/onlineMeetings/{id})
  • Delete an online meeting on behalf of a user (`DELETE /beta/users/{userId}/onlineMeetings/{id})

Note: Creating an online meeting creates a meeting on behalf of a user, but does not show it on the user's Calendar.

For more complex scenarios involving multiple permissions, see Permission scenarios.

On-premises publishing profiles permissions

Delegated permissions

Application permissions

OpenID Connect (OIDC) scopes

Remarks

You can use these scopes to specify artifacts that you want returned in Azure AD authorization and token requests. They are supported differently by the Azure AD v1.0 and v2.0 endpoints.

With the Azure AD v1.0 endpoint, only the openid scope is used. You specify it in the scope parameter in an authorization request to return an ID token when you use the OpenID Connect protocol to sign in a user to your app. For more information, see Authorize access to web applications using OpenID Connect and Azure Active Directory. To successfully return an ID token, you must also make sure that the User.Read permission is configured when you register your app.

With the Azure AD v2.0 endpoint, you specify the offline_access scope in the scope parameter to explicitly request a refresh token when using the OAuth 2.0 or OpenID Connect protocols. With OpenID Connect, you specify the openid scope to request an ID token. You can also specify the email scope, profile scope, or both to return additional claims in the ID token. You do not need to specify the User.Read permission to return an ID token with the v2.0 endpoint. For more information, see OpenID Connect scopes.

Important

The Microsoft Authentication Library (MSAL) currently specifies offline_access, openid, profile, and email by default in authorization and token requests. This means that, for the default case, if you specify these scopes explicitly, Azure AD may return an error.

Organization permissions

Delegated permissions

Application permissions

Example usage

Delegated

• Organization.Read.All: Get organization information (GET /organization).
• Organization.Read.All: Get the SKUs that the organization has subscribed to (GET /subscribedSkus).

Application

• Organization.ReadWrite.All: Update organization information (such as technicalNotificationMails) (PATCH /organization/{id}).

Delegated permissions

Application permissions

Example usage

Delegated

• OrgContact.Read.All: Get all organizational contacts (GET /contacts).

People permissions

Delegated permissions

Application permissions

Remarks

The People.Read.All permission is only valid for work and school accounts.

Example usage

Delegated

• People.Read: Read a list of relevant people (GET /me/people)
• People.Read.All: Read a list of relevant people to another user in the same organization (GET /users('{id})/people)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Privileged access permissions

Delegated permissions

Application permissions

Places permissions

Delegated permissions

Application permissions

Policy permissions

Delegated permissions

Application permissions

Example usage

The following usages are valid for both delegated and application permissions:

• Policy.Read.All: Read your organization's policies (GET /policies)
• Policy.Read.All: Read your organization's trust framework policies (GET /beta/trustFramework/policies)
• Policy.Read.All: Read your organization's feature rollout policies (GET /beta/directory/featureRolloutPolicies)
• Policy.ReadWrite.AccessReview: Read and write your organization's access review policies (PATCH /beta/policies/accessReviewPolicy)
• Policy.ReadWrite.ApplicationConfiguration: Read and write your organization's application configuration policies (POST /beta/policies/tokenLifetimePolicies)
• Policy.ReadWrite.AuthenticationFlows: Read and write your organization's authentication flows policy (PATCH /beta/policies/authenticationFlowsPolicy)
• Policy.ReadWrite.AuthenticationMethod: Use this permission to manage the settings of the authentication methods policy, including enabling and disabling authentication methods, allowing users and groups to use those methods, and configuring other settings related to the authentication methods that users may register and use in a tenant.
• Policy.ReadWrite.ConditionalAccess: Read and write your organization's conditional access policies (POST /beta/identity/conditionalAccess/policies)
• Policy.ReadWrite.CrossTenantAccess: Read and write your organization's cross tenant access policy (PATCH /beta/policies/crossTenantAccessPolicy)
• Policy.ReadWrite.FeatureRollout: Read and write your organization's feature rollout policies (POST /beta/directory/featureRolloutPolicies)
• Policy.ReadWrite.TrustFramework: Read and write your organization's trust framework policies (POST /beta/trustFramework/policies)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Presence permissions

Delegated permissions

Application permissions

Example usage

• Presence.Read: If you're signed in, retrieve your own presence information (GET /me/presence)
• Presence.Read.All: Retrieve the presence information of another user (GET /users/{id}/presence)
• Presence.Read.All: Retrieve the presence information of multiple users (POST /communications/getPresencesByUserId)
• Presence.ReadWrite:
  • If you're signed in, set the state of your presence session (POST /me/presence/setPresence)
  • If you're signed in, set your own preferred presence (POST /me/presence/setUserPreferredPresence)
• Presence.ReadWrite.All:
  • Set the state of a user's presence session as an application (POST /users/{id}/presence/setPresence)
  • Set the preferred presence of a user as an application (POST /users/{id}/presence/setUserPreferredPresence)

Programs and program controls permissions

Delegated permissions

Application permissions

Remarks

ProgramControl.Read.All and ProgramControl.ReadWrite.All are valid only for work or school accounts.

For an app with delegated permissions to read programs and program controls, the signed-in user must be a member of one of the following administrator roles: Global Administrator, Security Administrator, Security Reader or User Administrator. For an app with delegated permissions to write programs and program controls, the signed-in user must be a member of one of the following administrator roles: Global Administrator or User Administrator. For more information about administrator roles, see Assigning administrator roles in Azure Active Directory.

Records management permissions

Delegated permissions

Application permissions

Example usage

Delegated

• RecordsManagement.Read.All: Get the list of labels available to the user from Microsoft Purview Records maangement (GET /security/labels/retentionLabels)
• RecordsManagement.ReadWrite.All: Create a label in Microsoft Purview Records managment (POST /security/labels/retentionLabels/)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Reports permissions

Delegated permissions

Application permissions

Remarks

• Reports permissions are only valid for work or school accounts.
• For delegated permissions to allow apps to read service usage reports on behalf of a user, the tenant administrator must have assigned the user an Azure AD limited administrator role. For more details, see Authorization for APIs to read Microsoft 365 usage reports.

Example usage

Application

• Reports.Read.All: Read usage detail report of email apps with period of 7 days (GET /reports/EmailAppUsage(view='Detail',period='D7')/content).
• Reports.Read.All: Read activity detail report of email with date of '2017-01-01' (GET /reports/EmailActivity(view='Detail',data='2017-01-01')/content).
• Reports.Read.All: Read Microsoft 365 activations detail report (GET /reports/Office365Activations(view='Detail')/content).

For more complex scenarios involving multiple permissions, see Permission scenarios.

Role management permissions

Delegated permissions

Application permissions

Remarks

Caution

Permissions that allow granting authorization, such as RoleManagement.ReadWrite.Directory, allow an application to grant itself, other applications, or any user, additional privileges. Use caution when granting any of these permissions.

With the RoleManagement.Read.Directory permission an application can read directoryRoles and directoryRoleTemplates. This includes reading membership information for directory roles.

With the RoleManagement.ReadWrite.Directory permission an application can read and write directoryRoles (directoryRoleTemplates are readonly resources). This includes adding and removing members to and from directory roles.

Role management permissions are only valid for work or school accounts.

Example usage

• RoleManagement.Read.Directory: Read the list of available role templates (GET /directoryRoleTemplates)
• RoleManagement.Read.Directory: Read the list of activated roles in your directory (GET /directoryRoles)
• RoleManagement.Read.Directory: Read the list of members for a role (GET /directoryRoles/<id>/members)
• RoleManagement.Read.Directory: Read the list of administrative unit-scoped members for a role (GET /directoryRoles/<id>/scopedMembers)
• RoleManagement.ReadWrite.Directory: Activate a directory role from a role template (POST /directoryRoles)
• RoleManagement.ReadWrite.Directory: Add a member to a directory role (POST /directoryRoles/<id>/members)
• RoleManagement.ReadWrite.Directory: Add an administrative unit-scoped member to a directory role (POST /directoryRoles/<id>/scopedMembers)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Schedule management permissions (private preview)

Application permissions

Delegated permissions

Search permissions

Application permissions

Delegated permissions

Remarks

Search permissions are only valid for work or school accounts.

This search permission is only applicable to ingested data from the indexing API.

Access to data via search requires the read permission to the item. Ex : Files.Read.All to access files via search.

Example usage

Delegated

• ExternalItem.Read.All : Access external data from the search API (POST /search/query).

Search configuration permissions

Delegated permissions

Application permissions

Remarks

Search configuration permissions are only valid for work or school accounts.

Example usage

Delegated and Application

• SearchConfiguration.Read.All: Read the list of all bookmarks created for your tenant (GET /beta/search/bookmarks)
• SearchConfiguration.ReadWrite.All: Update or read all bookmarks created for your tenant (PATCH /beta/search/bookmarks/{id})

Security permissions

Delegated permissions

Application permissions

Remarks

Security permissions are valid only on work or school accounts.

Example usage

Delegated

• SecurityAlert.Read.All: Read all alerts in an organization that the user is allowed to read (GET /security/alerts_v2).
• SecurityAlert.ReadWrite.All: Read and write to all alerts in an organization that the user is allowed to read and write (GET /security/alerts_v2).
• SecurityEvents.Read.All: Read the list of all security alerts from all licensed security providers available in an organization (GET /beta/security/alerts).
• SecurityEvents.ReadWrite.All: Update or read security alerts from all licensed security providers available in an organization (PATCH /beta/security/alerts/{id}).

Application

• SecurityAlert.Read.All: Read all alerts in an organization (GET /security/alerts_v2).
• SecurityAlert.ReadWrite.All: Read and write to all alerts in an organization (GET /security/alerts).
• SecurityEvents.Read.All: Read the list of all security alerts from all licensed security providers available in an organization (GET /beta/security/alerts).
• SecurityEvents.ReadWrite.All: Update or read security alerts from all licensed security providers available in an organization (PATCH /beta/security/alerts/{id}).

Service communications permissions

Delegated permissions

Application permissions

Short Notes permissions (private preview)

Delegated permissions

Application permissions

Sites permissions

Delegated permissions

Application permissions

Remarks

Sites permissions are valid only on work or school accounts. The Sites.Selected application permission is available only in the Microsoft Graph API.

Example usage

Delegated

• Sites.Read.All: Read the lists on the SharePoint root site (GET /v1.0/sites/root/lists)
• Sites.ReadWrite.All: Create new list items in a SharePoint list (POST /v1.0/sites/root/lists/123/items)
• Sites.Manage.All: Add a new list to a SharePoint site (POST /v1.0/sites/root/lists)
• Sites.FullControl.All: Complete access to SharePoint sites and lists.

Subject rights request permissions

Delegated permissions

Application permissions

None.

Example usage

Delegated

• SubjectRightsRequest.Read.All_: Get the list of subject rights request available to the user (GET /privacy/subjectrightsrequests).
• SubjectRightsRequest.ReadWrite.All: Create a subject rights request (POST /privacy/subjectrightsrequests).

For more complex scenarios involving multiple permissions, see Permission scenarios.

Tasks permissions

Delegated permissions

Application permissions

None.

Remarks

Tasks permissions are used to control access for To Do tasks and Outlook tasks(deprecated). Access for Microsoft Planner tasks is controlled by Group permissions.

Shared permissions are currently only supported for work or school accounts. Even with Shared permissions, reads and writes may fail if the user who owns the shared content has not granted the accessing user permissions to modify content within the folder.

Example usage

Delegated

• Tasks.Read: Get all tasks in a user's mailbox (GET /me/outlook/tasks).
• Tasks.Read.Shared: Access tasks in a folder shared to you by another user in your organization (Get /users{id|userPrincipalName}/outlook/taskfolders/{id}/tasks).
• Tasks.ReadWrite: Add an event to the user's default task folder (POST /me/outlook/tasks).
• Tasks.Read: Get all uncompleted tasks in a user's mailbox (GET /users/{id | userPrincipalName}/outlook/tasks?$filter=status ne 'completed').
• Tasks.ReadWrite: Update a task in a user's mailbox (PATCH /users/{id | userPrincipalName}/outlook/tasks/id).
• Tasks.ReadWrite.Shared: Complete a task on behalf of another user (POST /users/{id | userPrincipalName}/outlook/tasks/id/complete).

For more complex scenarios involving multiple permissions, see Permission scenarios.

Taxonomy permissions

Delegated permissions

Remarks

Taxonomy permissions are valid only on work or school accounts.

Example usage

Delegated

• TermStore.Read.All: Read the termstore for the tenant (GET /termStore)
• TermStore.ReadWrite.All: Create new terms in the termStore (POST /termStore/sets/123/children)

Teams permissions

Delegated permissions

Application permissions

Team settings permissions

Delegated permissions

Application permissions

Teams activity permissions

Delegated permissions

Application permissions

Teams app permissions (deprecated)

Note

These permissions are deprecated. Use the equivalent TeamsAppInstallation.*.All permissions instead.

Delegated permissions

Application permissions

Teams app installation permissions

Delegated permissions

Application permissions

Teams device management permissions

Delegated permissions

Application permissions

Team member permissions

Delegated permissions

Application permissions

Team resource-specific consent permissions

Application permissions

Teams settings permissions

Delegated permissions

Application permissions

Teams tab permissions

Delegated permissions

Application permissions

Teams tag permissions

Delegated permissions

Application permissions

Tenant information permissions

Delegated permissions

Application permissions

Terms of use permissions

Delegated permissions

Remarks

All the permissions above are valid only for work or school accounts.

For an app to read or write all agreements or agreement acceptances with delegated permissions, the signed-in user must be assigned the Global Administrator, Conditional Access Administrator or Security Administrator role. For more information about administrator roles, see Assigning administrator roles in Azure Active Directory.

Example usage

Delegated

The following usages are valid for both delegated permissions:

• Agreement.Read.All: Read all terms of use agreements (GET /beta/agreements)
• Agreement.ReadWrite.All: Read and write all terms of use agreements (POST /beta/agreements)
• AgreementAcceptance.Read Read user terms of use acceptance statuses (GET /beta/me/agreementAcceptances)

For more complex scenarios involving multiple permissions, see Permission scenarios.

Threat assessment permissions

Delegated permissions

Application permissions

Remarks

Threat assessment permissions are valid only on work or school accounts.

Example usage

Delegated

• ThreatAssessment.ReadWrite.All: Read and write threat assessment requests (POST /informationProtection/threatAssessmentRequests)

Application

• ThreatAssessment.Read.All: Read threat assessment requests (GET /informationProtection/threatAssessmentRequests)

Universal Print permissions

Delegated permissions

Application permissions

Remarks

• To use the Universal Print service, the user or app's tenant must have an active Universal Print subscription in addition to the permissions listed earlier.

• Some permissions distinguish between print job metadata and payload. Metadata describes the configuration of a print job (its name and document configuration, such as whether it should be stapled or printed in color). Payload is the document data itself (the PDF or XPS file to be printed.)

• All PrintJob.* permissions also require at least Printer.Read.All (or a more prviliged permission) because print jobs are stored within printers.

Example usage

Delegated

• Printer.Read.All: Get a list of all printers in the tenant (GET /print/printers)
• PrintJob.Read.All: Get a list of all print jobs queued to a Printer (GET /print/printers/{id}/jobs)
• Printer.FullControl.All: Delete (unregister) a printer (DELETE /print/printers/{id})
• PrintJob.ReadWriteBasic.All: Update metadata (such as current status) of print jobs (PATCH /print/printers/{id}/jobs/{id})
• PrintJob.ReadWrite.All: Create print jobs and upload document data to them (POST /print/printers/{id}/jobs)

Application

• Printer.Read.All: Get a list of all printers in the tenant (GET /print/printers)

User permissions

Delegated permissions

Application permissions

Remarks

With the User.Read permission, an app can also read the basic company information of the signed-in user for a work or school account through the organization resource. The following properties are available: id, displayName, and verifiedDomains.

For work or school accounts, the full profile includes all of the declared properties of the User resource. On reads, only a limited number of properties are returned by default. To read properties that are not in the default set, use $select. The default properties are:

• displayName
• givenName
• jobTitle
• mail
• mobilePhone
• officeLocation
• preferredLanguage
• surname
• userPrincipalName

User.ReadWrite and User.Readwrite.All delegated permissions allow the app to update the following profile properties for work or school accounts:

• aboutMe
• birthday
• hireDate
• interests
• mobilePhone
• mySite
• pastProjects
• photo
• preferredName
• responsibilities
• schools
• skills

With the User.ReadWrite.All application permission, the app can update all of the declared properties of work or school accounts except for password.

With the User.ReadWrite.All delegated or application permission, updating another user's businessPhones, mobilePhone or otherMails is only allowed on users who are non-administrators or assigned one of the following roles: Directory Readers, Guest Inviter, Message Center Reader and Reports Reader. For more details, see Helpdesk (Password) Administrator in Azure AD available roles.

To read or write direct reports (directReports) or the manager (manager) of a work or school account, the app must have either User.Read.All (read only) or User.ReadWrite.All.

The User.ReadBasic.All permission constrains app access to a limited set of properties known as the basic profile. This is because the full profile might contain sensitive directory information. The basic profile includes only the following properties:

• displayName
• givenName
• mail
• photo
• surname
• userPrincipalName

To read the group memberships of a user (memberOf), the app must have either Group.Read.All or Group.ReadWrite.All. However, if the user also has membership in a directoryRole or an administrativeUnit, the app will need effective permissions to read those resources too, or Microsoft Graph will return an error. This means the app will also need Directory permissions, and, for delegated permissions, the signed-in user will also need sufficient privileges in the organization to access directory roles and administrative units.

With the User.ManageIdentities.All delegated or application permission, it is possible to update the identities (identities) of a user. This includes federated (or social identities) or local identities with email or name-based sign-in names.

Example usage

Delegated

• User.Read: Read the full profile for the signed-in user (GET /me).
• User.ReadWrite: Update the photo of the signed-in user (PUT /me/photo/$value).
• User.ReadBasic.All: Find all users whose name starts with "David" (GET /users?$filter=startswith(displayName,'David')).
• User.Read.All: Read a user's manager (GET /users/{id | userPrincipalName}/manager).

Application

• User.Read.All: Read all users and relationships through delta query (GET /beta/users/delta?$select=displayName,givenName,surname).
• User.ReadWrite.All: Update the photo for any user in the organization (PUT /users/{id | userPrincipalName}/photo/$value).

For more complex scenarios involving multiple permissions, see Permission scenarios.

User activity permissions

Delegated permissions

Application permissions

None.

Remarks

UserActivity.ReadWrite.CreatedByApp is valid for both Microsoft accounts and work or school accounts.

The CreatedByApp constraint associated with this permission indicates the service will apply implicit filtering to results based on the identity of the calling app, either the MSA app id or a set of app ids configured for a cross-platform application identity.

Example usage

Delegated

• UserActivity.ReadWrite.CreatedByApp: Get a list of recent unique user activities based on associated history items published in the last day. (GET /me/activities/recent).
• UserActivity.ReadWrite.CreatedByApp: Publish or update a user activity which may be resumed by the user of the application. (PUT /me/activities/%2Farticle%3F12345).
• UserActivity.ReadWrite.CreatedByApp: Publish or update a history item for a specified user activity in order to represent the period of user engagement. (PUT /me/activities/{id}/historyItems/{id}).
• UserActivity.ReadWrite.CreatedByApp: Delete a user activity in response to user initiated request or to remove invalid data. (DELETE /me/activities/{id}).
• UserActivity.ReadWrite.CreatedByApp: Delete a history item in response to user initiated request or to remove invalid data. (DELETE /me/activities/{id}/historyItems/{id}).

User authentication method permissions (preview)

Delegated permissions

Application permissions

Remarks

User authentication method permissions are used to manage authentication methods on users. With these permissions, a delegated user or application can register new authentication methods on a user, read the authentication methods the user already has registered, update those authentication methods, and remove them from the user.

With these permissions, all authentication methods can be read and managed on a user. This includes methods used for:

• Primary authentication (password)
• Second factor of multi-factor authentication/MFA (phone numbers)
• Self-Service Password Reset/SSPR (email address)

Windows updates permissions

Delegated permissions

Application permissions

Remarks

All the permissions above are valid only for work or school accounts.

For an app to read or write all Windows update deployment settings with delegated permissions, the signed-in user must be assigned the Global Administrator, Intune Administrator, or Windows Update Deployment Administrator role. For more information about administrator roles, see Assigning administrator roles in Azure Active Directory.

Example usage

Delegated

• WindowsUpdates.ReadWrite.All: Create a deployment (POST /beta/admin/windows/updates/deployments).

Application

• WindowsUpdates.ReadWrite.All: Create a deployment (POST /beta/admin/windows/updates/deployments).

Permission scenarios

This section shows some common scenarios that target user and group resources in an organization. The tables show the permissions that an app needs to be able to perform specific operations required by the scenario. Note that in some cases the ability of the app to perform specific operations will depend on whether a permission is an application or delegated permission. In the case of delegated permissions, the app's effective permissions will also depend on the privileges of the signed-in user within the organization. For more information, see Delegated permissions, Application permissions, and effective permissions.

Access scenarios on the User resource

Access scenarios on the Group resource

All permissions and IDs