Microsoft Graph permissions reference

Microsoft Graph exposes granular permissions that control the access that apps have to resources, like users, groups, and mail. As a developer, you decide which permissions for Microsoft Graph your app requests. When a user signs in to your app they, or, in some cases, an administrator, are given a chance to consent to these permissions. If the user consents, your app is given access to the resources and APIs that it has requested. For apps that don't take a signed-in user, permissions can be pre-consented to by an administrator when the app is installed or during sign-up.

Delegated permissions, Application permissions, and effective permissions

Microsoft Graph has two types of permissions: Delegated permissions and Application permissions.

  • Delegated permissions are used by apps that have a signed-in user present. For these apps either the user or an administrator consents to the permissions that the app requests and the app is delegated permission to act as the signed-in user when making calls to Microsoft Graph. Some Delegated permissions can be consented to by non-administrative users, but some higher-privileged permissions require administrator consent.

  • Application permissions are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons. Application permissions can only be consented by an administrator.

Effective permissions are the permissions that your app will have when making requests to Microsoft Graph. It is important to understand the difference between the Delegated and Application permissions that your app is granted and its effective permissions when making calls to Microsoft Graph.

  • For Delegated permissions, the effective permissions of your app will be the least privileged intersection of the Delegated permissions the app has been granted (via consent) and the privileges of the currently signed-in user. Your app can never have more privileges than the signed-in user. Within organizations, the privileges of the signed-in user may be determined by policy or by membership in one or more administrator roles. For more information about administrator roles, see Assigning administrator roles in Azure Active Directory.

For example, assume your app has been granted the User.ReadWrite.All Delegated permission. This permission nominally grants your app permission to read and update the profile of every user in an organization. If the signed-in user is a global administrator, your app will be able to update the profile of every user in the organization. However, if the signed-in user is not in an administrator role, your app will be able to update only the profile of the signed-in user. It will not be able to update the profiles of other users in the organization because the user that it has permission to act on behalf of does not have those privileges.

  • For Application permissions, the effective permissions of your app will be the full level of privileges implied by the permission. For example, an app that has the User.ReadWrite.All Application permission can update the profile of every user in the organization.

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.
  • 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, the effective permissions granted to your app may be constrained by the privileges of the signed-in user in the organization.

Microsoft accounts and work or school accounts

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

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. 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 cam 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.


Calendars permissions

Delegated permissions

Permission Display String Description Admin Consent Required
Calendars.Read Read user calendars Allows the app to read events in user calendars. No
Calendars.Read.Shared Read user and shared calendars Allows the app to read events in all calendars that the user can access, including delegate and shared calendars. No
Calendars.ReadWrite Have full access to user calendars Allows the app to create, read, update, and delete events in user calendars. No
Calendars.ReadWrite.Shared Read and write user and shared calendars Allows the app to create, read, update and delete events in all calendars the user has permissions to access. This includes delegate and shared calendars. No

Application permissions

Permission Display String Description Admin Consent Required
Calendars.Read Read calendars in all mailboxes Allows the app to read events of all calendars without a signed-in user. Yes
Calendars.ReadWrite Read and write calendars in all mailboxes Allows the app to create, read, update, and delete events of all calendars without a signed-in user. Yes

Remarks

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

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 bob@contoso.com (GET /users/{id | userPrincipalName}/events?$filter=organizer/emailAddress/address eq 'bob@contoso.com').
  • 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).
  • Calendars.Send: Send a message (POST /users/{id | userPrincipalName}/sendCalendars).

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


Contacts permissions

Delegated permissions

Permission Display String Description Admin Consent Required
Contacts.Read Read user contacts Allows the app to read user contacts. No
Contacts.Read.Shared Read user and shared contacts Allows the app to read contacts that the user has permissions to access, including the user's own and shared contacts. No
Contacts.ReadWrite Have full access to user contacts Allows the app to create, read, update, and delete user contacts. No
Contacts.ReadWrite.Shared Read and write user and shared contacts Allows the app to create, read, update and delete contacts that the user has permissions to, including the user's own and shared contacts. No

Application permissions

Permission Display String Description Admin Consent Required
Contacts.Read Read contacts in all mailboxes Allows the app to read all contacts in all mailboxes without a signed-in user. Yes
Contacts.ReadWrite Read and write contacts in all mailboxes Allows the app to create, read, update, and delete all contacts in all mailboxes without a signed-in user. Yes

Remarks

Only the Contacts.Read and Contacts.ReadWrite Delegated permissions are valid for Microsoft accounts.

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 /user/{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.


Device permissions

Delegated permissions

None.

Application permissions

Permission Display String Description Admin Consent Required
Device.ReadWrite.All Read and write devices Allows the app to read and write all device properties without a signed in user. Does not allow device creation, device deletion or update of device alternative security identifiers. Yes

Remarks

This permission is valid on for apps that target organizations.

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.


Microsoft Intune Device Management permissions

Delegated permissions

None.

Application permissions

Permission Display String Description Admin Consent Required
DeviceManagementServiceConfiguration.Read.All Read Microsoft Intune configuration (preview) Allows the app to read Microsoft Intune service properties including device enrollment and third party service connection configuration. Yes
DeviceManagementServiceConfiguration.ReadWrite.All Read and write Microsoft Intune configuration (preview) Allows the app to read and write Microsoft Intune service properties including device enrollment and third party service connection configuration. Yes
DeviceManagementConfiguration.Read.All Read Microsoft Intune device configuration and policies (preview) Allows the app to read properties of Microsoft Intune-managed device configuration and device compliance policies and their assignment to groups. Yes
DeviceManagementConfiguration.ReadWrite.All Read and write Microsoft Intune device configuration and policies (preview) Allows the app to read and write properties of Microsoft Intune-managed device configuration and device compliance policies and their assignment to groups. Yes
DeviceManagementApps.Read.All Read Microsoft Intune apps (preview) Allows the app to read the properties, group assignments and status of apps, app configurations and app protection policies managed by Microsoft Intune. Yes
DeviceManagementApps.ReadWrite.All Read and write Microsoft Intune apps (preview) Allows the app to read and write the properties, group assignments and status of apps, app configurations and app protection policies managed by Microsoft Intune. Yes
DeviceManagementRBAC.Read.All Read Microsoft Intune RBAC settings (preview) Allows the app to read the properties relating to the Microsoft Intune Role-Based Access Control (RBAC) settings. Yes
DeviceManagementRBAC.ReadWrite.All Read and write Microsoft Intune RBAC settings (preview) Allows the app to read and write the properties relating to the Microsoft Intune Role-Based Access Control (RBAC) settings. Yes
DeviceManagementManagedDevices.Read.All Read Microsoft Intune devices (preview) Allows the app to read the properties of devices managed by Microsoft Intune. Yes
DeviceManagementManagedDevices.ReadWrite.All Read and write Microsoft Intune devices (preview) Allows the app to read and write the properties of devices managed by Microsoft Intune. Does not allow high impact operations such as remote wipe and password reset on the device’s owner. Yes
DeviceManagementManagedDevices.PrivilegedOperations.All Perform user-impacting remote actions on Microsoft Intune devices (preview) Allows the app to perform remote high impact actions such as wiping the device or resetting the passcode on devices managed by Microsoft Intune. Yes

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

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.


Directory permissions

Delegated permissions

Permission Display String Description Admin Consent Required
Directory.Read.All Read directory data Allows the app to read data in your organization's directory, such as users, groups and apps. Yes
Directory.ReadWrite.All Read and write directory data Allows the app to read and write data in your organization's directory, such as users, and groups. It does not allow the app to delete users or groups, or reset user passwords. Yes
Directory.AccessAsUser.All Access directory as the signed-in user Allows the app to have the same access to information in the directory as the signed-in user. Yes

Application permissions

Permission Display String Description Admin Consent Required
Directory.Read.All Read directory data Allows the app to read data in your organization's directory, such as users, groups and apps, without a signed-in user. Yes
Directory.ReadWrite.All Read and write directory data Allows the app to read and write data in your organization's directory, such as users, and groups, without a signed-in user. Does not allow user or group deletion. Yes

Remarks

Directory permissions are not supported on Microsoft accounts.

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 Directory node in the v1.0 and beta API reference documentation. These include administrative units, directory roles, directory settings, policy, and many more.

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
  • Note: No rights to reset user passwords
  • Note: No rights to delete resources (including users or groups)
  • Note: 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.


Files permissions

Delegated permissions

Permission Display String Description Admin Consent Required
Files.Read Read user files and files shared with user Allows the app to read the signed-in user's files and files shared with the user. No
Files.Read.All Read all files that user can access Allows the app to read all files the signed-in user can access. No
Files.ReadWrite Have full access to user files and files shared with user Allows the app to read, create, update and delete the signed-in user's files and files shared with the user. No
Files.ReadWrite.All Have full access to all files user can access Allows the app to read, create, update and delete all files the signed-in user can access. No
Files.ReadWrite.AppFolder Have full access to the application's folder (preview) (Preview) Allows the app to read, create, update and delete files in the application's folder. No
Files.Read.Selected Read files that the user selects (preview) Limited support in Microsoft Graph - see Remarks
(Preview) Allows the app to read files that the user selects. The app has access for several hours after the user selects a file.
No
Files.ReadWrite.Selected Read and write files that the user selects (preview) Limited support in Microsoft Graph -- see Remarks
(Preview) Allows the app to read and write files that the user selects. The app has access for several hours after the user selects a file.
No

Application permissions

Permission Display String Description Admin Consent Required
Files.Read.All Read all files that user can access (preview) Limited support in Microsoft Graph
(Preview) Allows the app to read all files in all site collections without a signed in user.
Yes
Files.ReadWrite.All Have full access to all files user can access (preview) Limited support in Microsoft Graph
(Preview) Allows the app to read, create, update and delete all files in all site collections without a signed in user.
Yes

Remarks

Support for permissions in preview

Delegated permissions:

  • Files.Read.Selected and Files.ReadWrite.Selected are not yet supported by Microsoft Graph. For backward compatibility these permissions can be configured and included in authorization requests, but no privileges are granted by Microsoft Graph. Support for these permissions is planned in the future.
  • Files.ReadWrite.AppFolder_ is supported on Microsoft accounts only.

Application permissions:

  • Files.Read.All and Files.ReadWrite.All are currently not fully supported by Microsoft Graph; however, some privileges are granted with these permissions. Full support is planned soon.

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/rgregg@contoso.com/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.


Group permissions

Delegated permissions

Permission Display String Description Admin Consent Required
Group.Read.All Read all groups Allows the app to list groups, and to read their properties and all group memberships on behalf of the signed-in user. Also allows the app to read calendar, conversations, files, and other group content for all groups the signed-in user can access. Yes
Group.ReadWrite.All Read and write all groups Allows the app to create groups and read all group properties and memberships on behalf of the signed-in user. Additionally allows group owners to manage their groups and allows group members to update group content. Yes

Application permissions

Permission Display String Description Admin Consent Required
Group.Read.All Read all groups Allows the app to read memberships for all groups without a signed-in user. Note that not all group API supports access using app-only permissions. See known issues for examples. Yes
Group.ReadWrite.All Read and write all groups Allows the app to create groups, read and update group memberships, and delete groups. All of these operations can be performed by the app without a signed-in user. Note that not all group API supports access using app-only permissions. See known issues for examples. Yes

Remarks

Group functionality is not supported on Microsoft accounts.

For Office 365 groups, Group permissions grant the app access to the contents of the group; for example, conversations, files, notes, and so on. Group permissions are also used to control access to Microsoft Planner resources and APIs.

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.

Example usage

Delegated

  • Group.Read.All : Read all Office 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 Office 365 group content like conversations (GET /groups/{id}/conversations).
  • Group.ReadWrite.All : Update group properties, like photo (PUT /groups/{id}/photo/$value).
  • Group.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 an Office 365 group's calendar (POST /groups/{id}/events).

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


Identity Risk Event permissions

Delegated permissions

Permission Display String Description Admin Consent Required
IdentityRiskEvent.Read.All Read identity risk event information Allows the app to read identity risk event information for all users in your organization on behalf of the signed-in user. Yes

Application permissions

Permission Display String Description Admin Consent Required
IdentityRiskEvent.Read.All Read identity risk event information Allows the app to read identity risk event information for all users in your organization without a signed-in user. Yes

Remarks

IdentityRiskEvent.Read.All is 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 administrator roles: Global Administrator, Security Administrator, or Security Reader. 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:

  • Read all risk events generated for all users in the tenant (GET /beta/identityRiskEvents)
  • Read malware risk events generated by the Dorknet botnet (GET /beta/malwareRiskEvents?$filter=malwareName eq 'Dorkbot')
  • Read most recent 50 risk events (GET /beta/identityRiskEvents?$orderBy=riskEventDateTime desc&top=50)

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


Mail permissions

Delegated permissions

Permission Display String Description Admin Consent Required
Mail.Read Read user mail Allows the app to read email in user mailboxes. No
Mail.ReadWrite Read and write access to user mail Allows the app to create, read, update, and delete email in user mailboxes. Does not include permission to send mail. No
Mail.Read.Shared Read user and shared mail Allows the app to read mail that the user can access, including the user's own and shared mail. No
Mail.ReadWrite.Shared Read and write user and shared mail Allows the app to create, read, update, and delete mail that the user has permission to access, including the user's own and shared mail. Does not include permission to send mail. No
Mail.Send Send mail as a user Allows the app to send mail as users in the organization. No
Mail.Send.Shared Send mail on behalf of others Allows the app to send mail as the signed-in user, including sending on-behalf of others. No
MailboxSettings.Read Read user mailbox settings Allows the app to the read user's mailbox settings. Does not include permission to send mail. No
MailboxSettings.ReadWrite Read and write user mailbox settings Allows the app to create, read, update, and delete user's mailbox settings. Does not include permission to send mail. No

Application permissions

Permission Display String Description Admin Consent Required
Mail.Read Read mail in all mailboxes Allows the app to read mail in all mailboxes without a signed-in user. Yes
Mail.ReadWrite Read and write mail in all mailboxes Allows the app to create, read, update, and delete mail in all mailboxes without a signed-in user. Does not include permission to send mail. Yes
Mail.Send Send mail as any user Allows the app to send mail as any user without a signed-in user. Yes
MailboxSettings.Read Read all user mailbox settings Allows the app to read user's mailbox settings without a signed-in user. Does not include permission to send mail. No
MailboxSettings.ReadWrite Read and write all user mailbox settings Allows the app to create, read, update, and delete user's mailbox settings without a signed-in user. Does not include permission to send mail. Yes

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 bob@contoso.com (GET /users/{id | userPrincipalName}/messages?$filter=from/emailAddress/address eq 'bob@contoso.com').
  • 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.


Member permissions

Delegated permissions

None.

Application permissions

Permission Display String Description Admin Consent Required
Member.Read.Hidden Read all hidden memberships Allows the app to read the memberships of hidden groups and administrative units without a signed-in user. Yes

Remarks

Membership in some Office 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, an Office 365 group that represents students enrolled in a class).

Example usage

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

Permission Display String Description Admin Consent Required
Notes.Read Read user OneNote notebooks Allows the app to read the titles of OneNote notebooks and sections and to create new pages, notebooks, and sections on behalf of the signed-in user. No
Notes.Create Create user OneNote notebooks Allows the app to read the titles of OneNote notebooks and sections and to create new pages, notebooks, and sections on behalf of the signed-in user. No
Notes.ReadWrite Read and write user OneNote notebooks Allows the app to read, share, and modify OneNote notebooks on behalf of the signed-in user. No
Notes.Read.All Read all OneNote notebooks that user can access Allows the app to read OneNote notebooks that the signed-in user has access to in the organization. No
Notes.ReadWrite.All Read and write all OneNote notebooks that user can access Allows the app to read, share, and modify OneNote notebooks that the signed-in user has access to in the organization. No
Notes.ReadWrite.CreatedByApp Limited notebook access (deprecated) Deprecated
Do not use. No privileges are granted by this permission.
No

Application permissions

Permission Display String Description Admin Consent Required
Notes.Read.All Read all OneNote notebooks Allows the app to read all the OneNote notebooks in your organization, without a signed-in user. Yes
Notes.ReadWrite.All Read and write all OneNote notebooks Allows the app to read, share, and modify all the OneNote notebooks in your organization, without a signed-in user. Yes

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.


OpenID permissions

Delegated permissions

Permission Display String Description Admin Consent Required
email View users' email address Allows the app to read your users' primary email address. No
offline_access Access user's data anytime Allows the app to read and update user data, even when they are not currently using the app. No
openid Sign users in Allows users to sign in to the app with their work or school accounts and allows the app to see basic user profile information. No
profile View users' basic profile Allows the app to see your users' basic profile (name, picture, user name). No

Application permissions

None.


People permissions

Delegated permissions

Permission Display String Description Admin Consent Required
People.Read Read users' relevant people lists (preview) Allows the app to read a ranked list of relevant people of the signed-in user. The list includes local contacts, contacts from social networking, your organization's directory, and people from recent communications (such as email and Skype). No

Application permissions

None.

Remarks

Example usage

Delegated

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


Reports permissions

Delegated permissions

None.

Application permissions

Permission Display String Description Admin Consent Required
Reports.Read.All Read all usage reports Allows an app to read all service usage reports without a signed-in user. Services that provide usage reports include Office 365 and Azure Active Directory. Yes

Remarks

Reports permissions are only valid for work or school accounts.

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 Office 365 activations detail report (GET /reports/Office365Activations(view='Detail')/content)

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


Sites permissions

Delegated permissions

Permission Display String Description Admin Consent Required
Sites.Read.All Read items in all site collections Allows the application to read documents and list items in all site collections on behalf of the signed-in user. No
Sites.ReadWrite.All Read and write items in all site collections Allows the application to edit or delete documents and list items in all site collections on behalf of the signed-in user. No

Application permissions

None.

Remarks

Sites permissions are valid only on work or school accounts.

Example usage

Delegated

  • Sites.Read.All : Read the lists on the SharePoint root site (GET /beta/sharePoint/site/lists)
  • Sites.ReadWrite.All : Create new list items in a SharePoint list (POST /beta/sharePoint/site/lists/123/items)

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


Tasks permissions

Delegated permissions

Permission Display String Description Admin Consent Required
Tasks.Read Read user tasks Allows the app to read user tasks. No
Tasks.Read.Shared Read user and shared tasks Allows the app to read tasks a user has permissions to access, including their own and shared tasks. No
Tasks.ReadWrite Create, read, update and delete user tasks and containers Allows the app to create, read, update and delete tasks and containers (and tasks in them) that are assigned to or shared with the signed-in user. No
Tasks.ReadWrite.Shared Read and write user and shared tasks Allows the app to create, read, update, and delete tasks a user has permissions to, including their own and shared tasks. No

Application permissions

None.

Remarks

Tasks permissions are used to control access for Outlook tasks. 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/outook/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.


User permissions

Delegated permissions

Permission Display String Description Admin Consent Required
User.Read Sign-in and read user profile Allows users to sign-in to the app, and allows the app to read the profile of signed-in users. It also allows the app to read basic company information of signed-in users. No
User.ReadWrite Read and write access to user profile Allows the app to read your profile. It also allows the app to update your profile information on your behalf. No
User.ReadBasic.All Read all users' basic profiles Allows the app to read a basic set of profile properties of other users in your organization on behalf of the signed-in user. This includes display name, first and last name, email address and photo. No
User.Read.All Read all users' full profiles Allows the app to read the full set of profile properties, reports, and managers of other users in your organization, on behalf of the signed-in user. Yes
User.ReadWrite.All Read and write all users' full profiles Allows the app to read and write the full set of profile properties, reports, and managers of other users in your organization, on behalf of the signed-in user. Also allows the app to create and delete users as well as reset user passwords on behalf of the signed-in user. Yes
User.Invite.All Invite guest users to the organization Allows the app to invite guest users to your organization, on behalf of the signed-in user. Yes

Application permissions

Permission Display String Description Admin Consent Required
User.Read.All Read all users' full profiles Allows the app to read the full set of profile properties, group membership, reports and managers of other users in your organization, without a signed-in user. Yes
User.ReadWrite.All Read and write all users' full profiles Allows the app to read and write the full set of profile properties, group membership, reports and managers of other users in your organization, without a signed-in user. Also allows the app to create and delete non-administrative users. Does not allow reset of user passwords. Yes
User.Invite.All Invite guest users to the organization Allows the app to invite guest users to your organization, without a signed-in user. Yes

Remarks

The only permissions valid for Microsoft accounts are User.Read and User.ReadWrite. For work or school accounts, all permissions are valid.

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.

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.

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 /user/{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 /user/{id | userPrincipalName}/photo/$value).

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


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

App tasks involving User Req