Microsoft Graph API

Introduction to Microsoft Graph

Microsoft Graph is the gateway to data and intelligence in Microsoft 365. It provides a unified API model to access data across Microsoft cloud services, including:

  • Azure Active Directory (now Microsoft Entra ID)
  • Exchange Online
  • SharePoint Online
  • OneDrive
  • Teams
  • And more...

You can use Microsoft Graph to build applications that connect with your organization's data, enabling scenarios like productivity boosts, intelligent insights, and seamless collaboration.

Authentication and Authorization

Microsoft Graph uses OAuth 2.0 for authentication and authorization. You'll need to register your application in Azure Active Directory (Microsoft Entra ID) to obtain client credentials and define the permissions your app requires.

Common authentication flows include:

  • Authorization Code Flow: For web applications where a user signs in.
  • Client Credentials Flow: For daemon services or backend applications accessing resources without direct user interaction.
  • On-Behalf-Of Flow: For services that need to call a downstream service on behalf of a user.

Access tokens obtained from Microsoft Identity Platform are used to authenticate requests to Microsoft Graph. The scope of the access token determines the level of access the application has to specific resources.

Permissions

Microsoft Graph employs a robust permissions model to ensure data security and privacy. Permissions are categorized into:

  • Delegated permissions: An application acts on behalf of a signed-in user.
  • Application permissions: An application acts as itself, without a signed-in user.

Each API endpoint has specific permission requirements. It's crucial to request only the minimum necessary permissions to adhere to the principle of least privilege.

API Endpoints

Microsoft Graph exposes a rich set of RESTful API endpoints. The base URL for Microsoft Graph is typically https://graph.microsoft.com/v1.0/ or https://graph.microsoft.com/beta/ for pre-release features.

Users

Access information about users in your organization.

GET https://graph.microsoft.com/v1.0/users

Retrieves a list of users. Requires User.Read.All or User.ReadBasic.All delegated permissions, or User.Read.All application permissions.

GET https://graph.microsoft.com/v1.0/users/{id}

Retrieves a specific user by ID. Requires User.Read.All or User.ReadBasic.All delegated permissions, or User.Read.All application permissions.

POST https://graph.microsoft.com/v1.0/users

Creates a new user. Requires User.ReadWrite.All delegated or application permissions.

Request Body Example:

{
  "accountEnabled": true,
  "displayName": "Adele Vance",
  "mailNickname": "AdeleV",
  "userPrincipalName": "AdeleV@contoso.com",
  "passwordProfile": {
    "forceChangePasswordNextSignIn": true,
    "password": "YourPassword"
  }
}

Groups

Manage Microsoft 365 groups, security groups, and distribution lists.

GET https://graph.microsoft.com/v1.0/groups

Retrieves a list of groups. Requires Group.Read.All or Group.ReadBasic.All delegated permissions, or Group.Read.All application permissions.

GET https://graph.microsoft.com/v1.0/groups/{id}/members

Retrieves the members of a specific group. Requires appropriate Group.Read.All or Member.Read.All permissions.

Files (Drive)

Access and manage files and folders stored in OneDrive and SharePoint.

GET https://graph.microsoft.com/v1.0/me/drive/root/children

Lists the files and folders in the root of the signed-in user's OneDrive. Requires Files.Read or Files.ReadWrite delegated permissions.

GET https://graph.microsoft.com/v1.0/sites/{siteId}/drives/{driveId}/root/children

Lists children of the root folder in a specific SharePoint site's drive. Requires appropriate SharePoint permissions.

Mail

Send, receive, and manage emails.

GET https://graph.microsoft.com/v1.0/me/messages

Retrieves the messages in the signed-in user's mailbox. Requires Mail.Read delegated permissions.

POST https://graph.microsoft.com/v1.0/me/sendMail

Sends an email. Requires Mail.Send delegated permissions.

Request Body Example:

{
  "message": {
    "subject": "Meeting Update",
    "body": {
      "contentType": "Text",
      "content": "The meeting has been rescheduled to Friday."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "user@example.com"
        }
      }
    ]
  },
  "saveToSentItems": "true"
}

SDKs and Tools

Microsoft provides Software Development Kits (SDKs) for various programming languages to simplify interaction with Microsoft Graph. These SDKs handle authentication, request building, and response parsing.

  • Microsoft Graph SDK for JavaScript
  • Microsoft Graph SDK for .NET
  • Microsoft Graph SDK for Java
  • Microsoft Graph SDK for Python
  • Microsoft Graph PowerShell SDK

Additionally, the Graph Explorer is an invaluable tool for testing Microsoft Graph APIs directly in your browser without writing code.