Microsoft Graph
Microsoft Graph is a unified RESTful web API that serves as the primary gateway to data and intelligence across Microsoft 365, Microsoft Entra, and other cloud services, enabling developers to build applications that access and interact with rich, people-centric resources such as user profiles, emails, files, and collaboration tools through a single endpoint at https://graph.microsoft.com.[1] Launched in November 2015 as a comprehensive platform for modern work, initially previewed earlier that year as the Office 365 Unified API and reaching general availability under the Microsoft Graph name at the Microsoft Connect() event, it empowers organizations and consumers by extending Microsoft 365 experiences and integrating insights from productivity, security, and device management services.[1][2]
Key features of Microsoft Graph include support for authentication via Microsoft Entra ID, scalable data delivery through Microsoft Graph Data Connect to Azure storage, and integration capabilities like Copilot connectors for incorporating external data sources into AI-driven applications.[1] Developers can use SDKs in languages such as .NET, JavaScript, Java, and Python to simplify API interactions, while tools like Graph Explorer allow for testing and exploration of endpoints without custom coding.[1] The API supports both v1.0 for stable, generally available features and beta endpoints for preview functionalities, ensuring flexibility for production and experimental use.[3]
Microsoft Graph provides access to a wide array of services, categorized by productivity, collaboration, security, and more, including Outlook for mail and calendars, OneDrive and SharePoint for file management, Teams for messaging and meetings, and Intune for device oversight.[4] In the productivity domain, it exposes data from Excel workbooks, OneNote pages, and To Do tasks; collaboration features cover Planner plans, Viva Engage communities, and SharePoint lists.[4] Security and intelligence aspects include Microsoft Entra ID for identity management, Defender for threat detection, and Purview for eDiscovery, alongside education-specific resources like class rosters and business applications such as Dynamics 365.[4] This interconnected access facilitates intelligent applications that enhance workplace efficiency, such as personalized insights via Delve or automated workflows across Microsoft ecosystems.[4]
Introduction
Definition and Purpose
Microsoft Graph is a RESTful web API that serves as a unified gateway to data and intelligence across Microsoft cloud services, including Microsoft 365, Microsoft Entra ID, Windows, and others such as Enterprise Mobility + Security and Dynamics 365 Business Central.[1][5] It enables developers to access a wide range of resources, from user profiles and organizational hierarchies to content like emails, files, calendars, and activity data, all through a consistent interface.[1]
The primary purpose of Microsoft Graph is to empower developers to create intelligent applications that integrate seamlessly with Microsoft ecosystems, fostering enhanced productivity, collaboration, and security for organizations and consumers.[1] By connecting to people-centric data—such as user interactions, messages, documents, and tasks—it allows applications to derive real-time insights and automate workflows that reflect how individuals and teams operate within these services.[4] This focus on relational, activity-based data distinguishes it as a platform for building context-aware solutions rather than isolated data retrieval.[1]
At its core, Microsoft Graph operates via a single endpoint URL, https://graph.microsoft.com, which supports the OData v4 protocol for querying and manipulating resources.[5] This standardization simplifies development by allowing HTTP methods like GET, POST, PUT, and DELETE to interact with entities in a predictable manner, often using SDKs for various programming languages to abstract the underlying calls.[5]
One of the key benefits of Microsoft Graph is its unified access model, which eliminates the need to manage multiple siloed APIs for different Microsoft services, thereby reducing development complexity and maintenance overhead.[1] It facilitates real-time data retrieval and analytics, enabling organizational applications to provide actionable intelligence, such as personalized recommendations or security alerts based on integrated data streams.[1]
Launch and Evolution
Microsoft Graph originated as the Office 365 Unified API, which was first previewed at the Microsoft Build conference in April 2015 to consolidate access to data across Office 365 services like Exchange, SharePoint, and OneDrive through a single RESTful endpoint.[6] This unified approach aimed to simplify developer integration by providing a consistent API surface for productivity data, replacing fragmented service-specific endpoints. The preview allowed early adopters to experiment with features such as unified authentication via Azure Active Directory and OData-based querying.[7]
In November 2015, at the Microsoft Connect() event, the API reached general availability and was rebranded as Microsoft Graph to signify its expanded ambition as a connected graph of intelligence spanning not only Office 365 but also emerging integrations with Windows and Enterprise Mobility + Security services.[2] This rebranding underscored a shift toward a more holistic platform for accessing user activities, relationships, and insights across Microsoft's ecosystem, enabling developers to build applications that leverage contextual data like user collaboration patterns.[8] By 2016, Microsoft Graph had evolved to support broader enterprise scenarios, including initial connections to Azure services for enhanced identity and device management.
Key expansions marked subsequent milestones. At the 2017 Build conference, Microsoft announced enhanced cross-device connectivity through Project Rome (later Proximity SDK), allowing seamless experiences across Windows, Android, and iOS via Microsoft Graph APIs for activity feeds and file sharing.[9] In 2020, Microsoft deepened integration with Azure Active Directory (now Microsoft Entra ID) by announcing the deprecation of the legacy Azure AD Graph API, urging migration to Microsoft Graph for all identity-related operations to unify access to users, groups, and permissions.[10] Recent updates from 2023 to 2025 have focused on AI and compliance: in 2023, Microsoft Graph Data Connect entered public preview for scalable bulk data export to analytics platforms like Azure Synapse, enabling enterprise-scale insights while adhering to governance controls.[11] By 2024, support for Microsoft 365 Copilot connectors was introduced, allowing third-party data ingestion into the graph for AI-driven experiences.[12] In September 2025, enhancements to eDiscovery APIs improved processing for large datasets and expanded file type support, while new activity logs provided tenant-level audit trails of HTTP requests for monitoring and compliance.[13][14]
Microsoft Graph's versioning policy maintains stability with the v1.0 endpoint for production-ready APIs and a beta endpoint for previews, ensuring backward compatibility while allowing iterative improvements; deprecated features, such as the Azure AD Graph, were initially slated for retirement by June 2023 but extended and retired on June 30, 2025, to facilitate migrations.[15][16] This evolution has been driven by a cloud-first strategy emphasizing AI-powered insights, with annual "What's New" releases introducing features like advanced change notifications and semantic indexing to support intelligent applications.[17] In November 2025, further updates included generally available enhancements to backup storage, such as expanded driveItem restore methods; improved device and app management for Cloud PC; and new capabilities in security alerts and incidents.[17]
Architecture
API Structure
Microsoft Graph employs a RESTful architecture, utilizing standard HTTP protocols to enable developers to interact with data and services across Microsoft 365, Windows, and Enterprise Mobility + Security. The API adheres to the OData v4 protocol, which standardizes querying, filtering, and expanding resources through URL-based parameters. For instance, developers can retrieve a user's messages with filtering using a request like GET https://graph.microsoft.com/v1.0/me/messages?$filter=receivedDateTime ge 2023-01-01, allowing precise data retrieval without over-fetching. This OData compliance ensures interoperability and supports advanced query options such as $select for property projection and $expand for navigating related entities in a single call.[1][18]
The API supports core HTTP methods for CRUD operations: GET for reading resources, POST for creating new ones, PATCH for partial updates, and DELETE for removal. To optimize efficiency, Microsoft Graph allows batching of up to 20 requests in a single HTTP POST to the /v1.0/$batch or /beta/$batch endpoint, using a JSON payload that encapsulates multiple operations. An example batch request might include diverse actions like fetching user details, creating a calendar event, and deleting a message, all processed atomically with individual responses correlated by unique IDs. Endpoint versioning maintains stability with /v1.0 for production-ready features and /beta for experimental ones, all routed through a single global endpoint at https://graph.microsoft.com followed by resource-specific paths, such as /users/{id}/messages for accessing a user's inbox.[19][1]
Error handling follows standardized conventions, returning JSON objects with an error property containing a machine-readable code, a descriptive message, and optional innererror details. Client errors use 4xx status codes (e.g., 400 for bad requests, 403 for forbidden access), while server errors employ 5xx codes (e.g., 500 for internal errors, 503 for temporary unavailability). Throttling is enforced via 429 "Too Many Requests" responses when limits are exceeded, prompting retries after a delay specified in the Retry-After header; these limits vary by service and scenario to maintain reliability, often in the range of thousands of requests per short intervals depending on the resource. For scalability with large datasets, the API implements server-driven pagination, where responses include an @odata.nextLink property—a full URL with a skip token—for fetching subsequent pages, ensuring efficient handling of high-volume access without overwhelming clients.[20][21][22]
Data Model and Entities
Microsoft Graph employs a centralized data model that unifies resources across Microsoft cloud services, representing them as interconnected entities accessible through a single REST API endpoint. Core entities include User, which represents Microsoft Entra user accounts; Group, for Microsoft 365 groups and security groups; Message, for Outlook emails; DriveItem, for files and folders in OneDrive and SharePoint; and Event, for calendar appointments in Outlook. These entities encapsulate data from services like Microsoft 365, Microsoft Entra, and Dynamics 365, enabling developers to interact with diverse resources in a consistent manner.[1][23]
Relationships between entities are defined through navigational properties, allowing efficient traversal of data without requiring multiple API calls. For instance, the User entity's messages property links to a collection of Message entities in the user's mailbox, while the Group entity's members property connects to related User or Group entities. These properties, detailed in the Microsoft Graph metadata, support hierarchical and associative navigation, such as retrieving a user's direct reports via /users/{id}/directReports. This structure facilitates querying complex scenarios, like fetching events for a group by navigating from Group to its members and then to their calendars.[24]
To accommodate organization-specific needs, Microsoft Graph supports schema extensions and open extensions for adding custom properties to entities. Schema extensions enable the definition of strongly-typed custom data schemas, such as adding a departmentCode property to the User entity, which can be registered via the API and applied tenant-wide for discoverability and filtering. In contrast, open extensions allow flexible, untyped key-value pairs on individual resource instances, like attaching metadata to a specific Message without schema definition. Both extension types are managed through the Microsoft Graph API, with schema extensions limited to five definitions per owning application and open extensions capped at two per resource instance.[25][26]
Entities in Microsoft Graph adhere to a consistent schema pattern, inheriting common properties from base types like directoryObject or entity. These include id, a unique string identifier; createdDateTime, the ISO 8601 UTC timestamp of creation; and lastModifiedDateTime, the timestamp of the last update, which are read-only and support filtering operations. This uniformity ensures predictable data handling across resources. Additionally, delta queries provide change tracking by returning additions, updates, or deletions since the last request, using state tokens like @odata.deltaLink; for example, /me/mailFolders/inbox/messages/[delta](/page/Delta) tracks email changes efficiently, reducing full resource scans and respecting API throttling limits. Supported on entities like User, Group, Message, and DriveItem, delta queries include tokens that expire after periods such as seven days for directory objects.[23][27]
An intelligence layer overlays the data model, leveraging machine learning to derive insights from entity relationships and user interactions. This includes the Insights API, which generates activity feeds of trending documents or files used by a user, and the People API, which ranks relevant contacts based on communication patterns for recommendations. These derived insights, such as personalized file suggestions or collaboration trends, enhance applications without direct entity modifications, powering features in Microsoft 365 like Outlook's suggested contacts.[28]
Core Features and Services
Productivity Services
Microsoft Graph provides APIs that enable developers to integrate and manage individual productivity tools within Microsoft 365, focusing on personal data such as emails, calendars, files, tasks, notes, spreadsheets, and contacts. These APIs allow applications to perform create, read, update, and delete (CRUD) operations on user-specific resources, enhancing personal workflow efficiency without delving into team-based collaboration. By leveraging a unified endpoint at https://graph.microsoft.com, developers can access these services securely after obtaining appropriate delegated permissions.[1]
Mail and Calendar
The Mail API in Microsoft Graph supports access to users' primary mailboxes and shared mailboxes, enabling operations on emails stored in well-known folders like Inbox, Sent Items, and Drafts. Developers can retrieve, create, update, delete, forward, or reply to messages using the /me/messages endpoint or user-specific paths like /users/{id}/messages. Attachments can be added, retrieved, or removed as file or item attachments, with direct attachments limited to under 3 MB; larger files up to 150 MB require creating an upload session via /attachments/createUploadSession for iterative uploads. This facilitates personal email management, such as automating replies or organizing drafts.[29][30][31]
Complementing mail functionality, the Calendar API allows management of personal calendars and events through endpoints like /me/events or /users/{id}/events. Users can create, read, update, or delete single-instance and recurring events, including details like attendees, location, and body content. Attachments to events are supported up to 3 MB integrated directly into the event resource; larger files up to 150 MB require an upload session via /attachments/createUploadSession. Calendars can be organized into groups via /me/calendarGroups, and free/busy information is accessible for scheduling. These features enable applications to handle personal scheduling, such as adding reminders or syncing events across devices.[32][31]
Files and Storage
Microsoft Graph's OneDrive and SharePoint APIs provide robust file management for individual users, treating personal OneDrive as a drive resource accessible via /me/drive. Operations include uploading, downloading, and searching files and folders using /items endpoints, with support for metadata, thumbnails, and previews without full downloads. Developers can create sharing links with granular permissions, such as view-only or edit access, through /createLink on drive items, allowing secure personal file distribution. Special folders like Documents or Camera Roll are reachable via /drive/special/endpoint.value, promoting seamless integration for tasks like backing up photos or accessing recent files. Real-time coauthoring is available for Office files, enhancing personal productivity in document handling.[33]
Tasks and Notes
The To Do API enables personal task management by interacting with task lists and individual tasks via /me/todo/lists and /me/todo/lists/{listId}/tasks. Developers can create, read, update, or delete tasks, including subtasks (checklist items) and linked resources like email references, with delta queries for efficient synchronization across devices. This supports building apps that help users organize daily priorities, such as adding tasks from incoming messages or marking completions.[34]
For note-taking, the OneNote API offers CRUD operations on personal notebooks, sections, and pages using paths like /me/onenote/notebooks or /me/onenote/pages. Content can be created by posting HTML to page endpoints, read via GET requests for structure and text, updated with patches, or deleted entirely. This allows applications to extend OneNote for personal knowledge management, such as inserting notes programmatically or retrieving page hierarchies. Delegated permissions are required, ensuring user-controlled access.[35]
Excel Workbooks
Excel integration in Microsoft Graph targets personal workbooks stored in OneDrive or SharePoint, accessed through the /me/drive/items/{item-id}/workbook endpoint. Developers can read and write cells, ranges, tables, and charts using operations like GET /worksheets for listing sheets or PATCH /ranges for updating values and formulas. Charts can be added or imaged via /charts/add and /charts/{name}/image, while functions like PMT are callable through /functions. Sessions support persistent changes or temporary edits, with support limited to .xlsx format. This enables apps to automate personal data analysis, such as populating spreadsheets from external sources or generating reports.[36]
The personal contacts API manages Outlook contacts via /me/contacts or /users/{id}/contacts, supporting CRUD operations on contact resources stored in default or custom folders. Properties include email addresses, phone numbers, categories, and photos (via /photo endpoints), with features like follow-up flags and extensions for custom data. Developers can assign contacts to folders using /contactFolders, sync changes via notifications, and integrate with broader people data. This facilitates personal relationship management, such as updating contact details from CRM systems or categorizing connections.[37]
Collaboration Services
Microsoft Graph provides a suite of APIs designed to facilitate team-oriented collaboration within Microsoft 365, enabling developers to integrate shared workspaces, real-time communication, and content management into applications. These services emphasize multi-user interactions, such as group messaging, joint document editing, and coordinated scheduling, distinct from individual productivity tools. By leveraging these APIs, organizations can automate workflows for distributed teams, ensuring seamless connectivity across devices and platforms.[38]
The Teams and Channels APIs allow for the creation, management, and interaction with collaborative spaces in Microsoft Teams. Developers can create new teams associated with Microsoft 365 groups, add or remove members, and join teams programmatically to foster group collaboration. Channels within teams support posting messages, managing tabs for custom applications, and handling files shared among participants, enabling structured discussions and resource organization. For instance, the channel resource type facilitates CRUD operations on channel messages and files, supporting threaded conversations and integrations with external content.[39][40]
Online meetings and calls are managed through the cloud communications APIs, which support scheduling, joining, and overseeing virtual sessions in Teams. The /communications/calls endpoint enables the initiation of group calls, management of participant rosters, and access to meeting transcripts or recordings, enhancing remote collaboration. Developers can use the onlineMeeting resource to schedule events via the calendar API or directly through communications endpoints, including features like participant muting and lobby management for controlled interactions. This API set also integrates with bots for automated meeting assistance, such as reminders or real-time transcription.[41][42]
SharePoint sites and lists APIs enable comprehensive management of collaborative content repositories. Through the site resource type, developers can perform CRUD operations on sites, including creating subsites for team-specific workspaces and managing permissions for shared access. Lists support custom data structures with items that can be created, updated, or deleted, while document libraries handle file uploads and version control for joint editing. Wiki pages within sites allow for collaborative knowledge bases, with APIs for adding, editing, and retrieving content to support team documentation. Permissions can be granularly controlled via the site's permission resource, ensuring secure sharing among collaborators.[43][44]
Planner and Shifts APIs address task and schedule coordination for teams. The Planner API permits the creation of plans and tasks within Microsoft 365 groups, assigning responsibilities, setting due dates, and tracking progress through buckets and labels for organized workflows. Individual task management, such as updates or completions, can reference broader team plans but focuses on shared accountability. Shifts, integrated with Teams schedules, allow for creating, assigning, and approving work shifts, including time-off requests and swap proposals, to manage frontline worker rosters. The schedule resource type supports listing and updating shifts, with approval workflows to streamline operational collaboration.[45][46][47]
Viva tools extend collaboration via engagement and learning APIs. The Viva Engage API manages communities for social interactions, allowing creation of groups, posting updates, and handling roles to build internal networks and knowledge sharing. Engagement feeds enable threaded discussions and reactions among team members. Viva Learning APIs integrate learning content by registering providers and pushing modules, such as courses or resources, into shared feeds for collective upskilling. Developers can list and assign learning content via the learningContent resource, supporting collaborative professional development within teams.[48][49]
Security and Compliance Services
Microsoft Graph provides a suite of security and compliance services through its APIs, enabling organizations to protect data, manage identities, detect threats, and adhere to regulatory requirements across Microsoft 365 environments. These services integrate with tools like Microsoft Entra ID, Microsoft Defender, and Microsoft Purview to offer unified access to security intelligence and compliance workflows, allowing developers to build applications that automate threat response, audit activities, and data governance tasks.[50][51]
In the realm of identity and access management, Microsoft Graph leverages Microsoft Entra ID to facilitate user and group management, role assignments, and conditional access policies. Developers can use APIs such as /users, /groups, and /roles to query and update directory objects, while conditional access endpoints enable the enforcement of policies based on user risk, device compliance, and location. This integration supports fine-grained control over access to resources, ensuring that only authorized entities interact with sensitive data in Microsoft 365 services like Exchange and SharePoint.[50]
Threat protection features in Microsoft Graph center on aggregating and acting on security alerts from Microsoft Defender solutions. The /security/alerts endpoint allows retrieval of alerts from Microsoft Defender for Office 365, Endpoint, and Identity, providing details on detected threats, severity levels, and recommended remediation actions. Risk detections are surfaced through Entra ID Protection APIs, which identify anomalous sign-ins and compromised accounts, enabling proactive responses like automatic blocking or multi-factor authentication enforcement. These capabilities support incident correlation and advanced hunting queries using Kusto Query Language (KQL) to analyze up to 30 days of telemetry data.[52][53]
For eDiscovery and compliance, Microsoft Graph APIs enable searching, exporting, and holding content across mailboxes, sites, and Teams for legal and regulatory purposes, integrated with Microsoft Purview. The eDiscovery endpoints, such as /compliance/ediscovery/cases, automate case creation, custodian management, and content review, with September 2025 updates introducing advanced automation for processing large datasets, enhanced indexing controls, and faster export workflows in public preview. Retention policies are managed via Purview APIs like /compliance/retentionPolicies, which define rules for data preservation based on labels, locations, and durations to meet standards like GDPR or HIPAA. These tools streamline investigations by supporting repeatable workflows for tagging, redaction, and reporting without manual intervention.[51][54][55]
Activity logs in Microsoft Graph offer comprehensive auditing of API requests and user activities for tenant monitoring, providing an immutable record of HTTP interactions with the service. Accessible via the /auditLogs endpoint, these logs capture details like request timestamps, actors, targets, and outcomes, aiding in compliance audits and anomaly detection; general availability was achieved in September 2025, expanding visibility from sign-ins to full API call traces.[13]
Permissions scopes in Microsoft Graph distinguish between delegated and application permissions to enforce least-privilege access for security services. Delegated permissions require user consent and operate in the context of a signed-in user, suitable for interactive apps handling alerts or compliance tasks on behalf of individuals. Application permissions, granted tenant-wide via admin consent, allow daemon apps to access resources independently, such as bulk alert retrieval or policy management, with both types protected by Microsoft Entra roles like Security Reader or Compliance Administrator to prevent unauthorized data exposure.[56][50]
Authentication and Security
Authorization Methods
Microsoft Graph utilizes the OAuth 2.0 authorization framework to enable secure access to its resources, allowing applications to obtain access tokens that grant specific permissions without sharing user credentials.[57] This framework supports two primary access scenarios: delegated access, where the application acts on behalf of a signed-in user, and app-only access, where the application operates independently using its own identity.[57]
For delegated access, the authorization code flow is the recommended OAuth 2.0 grant type, particularly for web applications and interactive clients. In this flow, the application redirects the user to the Microsoft identity platform's /authorize endpoint to request consent for scopes such as User.Read (to read the user's profile) or Mail.Read (to read the user's mail). Upon user approval, an authorization code is returned, which the application exchanges at the /token endpoint for an access token and optionally a refresh token if the offline_access scope is included.[58] The access token, formatted as a Bearer token, is then used in API requests to Microsoft Graph, such as retrieving user data via GET https://graph.microsoft.com/v1.0/me.[](https://learn.microsoft.com/en-us/graph/auth-v2-user)
App-only access employs the OAuth 2.0 client credentials flow, suitable for daemon or background services without user interaction. The application authenticates directly with the /token endpoint using its client ID and secret (or certificate), requesting the scope https://graph.microsoft.com/.default to encompass all pre-consented application permissions, such as User.Read.All for reading all users' full profiles in the tenant.[59] Admin consent is required to grant these application-level permissions, ensuring elevated access is controlled.[59]
The Microsoft Identity Platform, built on Entra ID (formerly Azure Active Directory), serves as the underlying service for authentication and authorization in Microsoft Graph, handling app registration, token issuance, and identity verification across Microsoft ecosystems.[57] As of June 2024, new applications must be registered in a Microsoft Entra ID tenant to obtain a client ID and configure supported account types, such as single-tenant or multi-tenant; existing registrations with personal Microsoft accounts continue to function.[60] Access tokens are issued via endpoints like https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token.[59] Scopes define the granular permissions, distinguishing between delegated (user-context) and application (app-context) types, with examples like Files.Read for basic file access.[61]
OpenID Connect extends OAuth 2.0 in the Microsoft Identity Platform to provide user sign-in capabilities, issuing ID tokens alongside access tokens to convey user identity claims such as name and tenant ID.[58] These ID tokens enable applications to validate the user's authentication and retrieve profile information without additional Graph calls. Refresh tokens, obtained during the authorization code flow with the offline_access scope, allow applications to acquire new access tokens for long-lived sessions, maintaining access without repeated user interaction.[58]
Certificate-based authentication offers a secure alternative to client secrets for app-only scenarios, particularly for daemon applications. Developers upload a public certificate to the Entra ID app registration, using the corresponding private key to sign assertions or directly authenticate in the client credentials flow, reducing risks associated with secret management.[59]
Consent models in the Microsoft Identity Platform govern how permissions are granted, balancing user autonomy with administrative oversight. User consent allows individuals to approve delegated permissions during sign-in, prompting a dialog that details requested scopes like User.Read. Admin consent is mandatory for application permissions or sensitive delegated ones (e.g., Directory.Read.All), where tenant administrators grant access for the entire organization via the Entra admin center or the /adminconsent endpoint. Multi-tenant applications support consent across tenants, with options for preauthorization to streamline access for external users without individual prompts.[61]
Best Practices for Secure Access
Implementing secure access in Microsoft Graph applications requires adherence to established guidelines that minimize risks associated with authentication, authorization, and data exposure. Developers should prioritize the principle of least privilege by requesting only the minimal permissions necessary for the application's functionality, such as using User.Read instead of broader scopes like User.Read.All. This approach reduces the potential impact of compromised credentials, as recommended by Microsoft for all Entra ID-registered applications.[57] Regularly reviewing and revoking unnecessary permissions through Entra ID access reviews ensures ongoing compliance and limits long-term exposure; for instance, permissions should be audited every few months to align with evolving app needs.[62] Resource-specific consent permissions further enhance this by allowing granular access to individual items, such as specific chats via ChatMessage.Send.Chat, rather than entire resources. As of October 2025, new granular permissions for authentication methods, such as UserAuthMethod-Email.Read and UserAuthMethod-Passkey.ReadWrite.All, provide even finer control over identity and sign-in resources.[63][17]
Effective token management is crucial to prevent unauthorized access. Access tokens should be stored securely using Azure Key Vault or managed identities, avoiding hardcoding secrets in code or configuration files to mitigate exposure risks.[64] Opt for short-lived tokens, typically lasting one hour, and implement automated rotation for any client secrets or certificates used in authentication, leveraging tools like Azure Key Vault for seamless updates without service disruption.[64] The Microsoft Authentication Library (MSAL) simplifies this process by handling token acquisition, caching, and refresh automatically across platforms, ensuring compliance with OAuth 2.0 standards.[65] For Azure-hosted applications, managed identities provide a credential-free alternative, eliminating the need to manage secrets altogether while enforcing secure access to Graph resources.[66]
To maintain reliability and detect potential threats, applications must handle rate limiting proactively. When encountering HTTP 429 (Too Many Requests) errors, implement retries based on the Retry-After header value, or use exponential backoff if absent, to avoid exacerbating throttling.[21] Integrating Microsoft Graph activity logs with Azure Monitor enables real-time monitoring of API requests, including details like request URIs and response codes, for anomaly detection—such as unusual access patterns or repeated failures indicative of attacks.[13] This logging, which requires an Entra ID P1 or P2 license, allows correlation with sign-in logs to identify suspicious activities promptly.[13]
Enforcing multi-factor authentication (MFA) strengthens app registrations against unauthorized use. Configure Entra ID Conditional Access policies to require MFA for all interactive sign-ins to the Azure portal and app management interfaces, ensuring administrators and developers verify their identity.[67] For service principals and background processes, rely on managed identities or certificate-based authentication instead of passwords, combined with MFA policies for any human-involved workflows.[68]
Common pitfalls in Microsoft Graph implementations can undermine security if unaddressed. The OAuth 2.0 implicit grant flow, which exposes tokens directly in the browser, is deprecated due to vulnerabilities like interception; instead, use the authorization code flow with PKCE for single-page applications.[69] Additionally, test applications for token replay attacks by enabling token protection in Conditional Access, which binds tokens to specific devices and prevents reuse from unauthorized contexts.[70]
Development and Integration
Microsoft Graph provides official software development kits (SDKs) for several programming languages, designed to simplify the creation of high-quality, efficient, and resilient applications that interact with its APIs. These SDKs are auto-generated from the Graph metadata using the OpenAPI description, enabling type-safe calls and a discoverable programming experience. Supported languages include .NET, Java, JavaScript (for Node.js and browser environments), Python, and Go. For instance, in the .NET SDK, developers can use methods like graphServiceClient.Me.SendMail() to send emails programmatically.[71][72]
The Microsoft Graph Toolkit offers a collection of reusable, framework-agnostic web components and authentication providers to facilitate UI integration with Microsoft Graph data. Key components include mgt-login for user authentication and profile display, mgt-person for rendering user details such as photos, names, and emails, and mgt-agenda for showing calendar events. These components can be implemented with minimal code, such as embedding them directly in HTML to display a user's profile and schedule. However, the toolkit is deprecated, with a retirement period starting September 1, 2025, and full retirement planned for August 28, 2026; developers are encouraged to migrate to the core SDKs.[73]
Several tools support development and testing with Microsoft Graph. Graph Explorer is a web-based developer tool that allows users to explore APIs, run sample queries (e.g., retrieving a user's profile), prototype scenarios, and learn about required permissions, with support for full CRUD operations after signing in with a Microsoft 365 account.[74] Postman collections are available for Microsoft Graph, enabling developers to fork pre-built environments, configure authentication via Microsoft Entra app registrations, and test API requests across global and national cloud endpoints.[75] The Microsoft Graph PowerShell SDK serves as an API wrapper, providing cmdlets for managing identities and accessing services like SharePoint and Outlook; it supports modern authentication, least-privilege access, and cross-platform use on PowerShell 7 or later.[76]
Microsoft Graph Data Connect facilitates bulk data extraction from Microsoft 365 datasets, such as Entra ID, Outlook, Teams, and SharePoint, delivering it securely to Azure Storage in Parquet format for analytics workloads. This tool supports granular consent and integration with Microsoft Fabric, Azure Synapse Analytics, and Azure Data Factory, enabling enterprise-scale insights into areas like collaboration patterns and security.[77]
Microsoft 365 Copilot connectors allow organizations to ingest unstructured data from external sources into Microsoft Graph, enhancing Copilot's ability to provide contextual responses with semantic indexing and in-text citations. Over 100 prebuilt connectors are available for services like Azure, Box, Confluence, Google Drive, Salesforce, and ServiceNow, while custom connectors can be built using the Copilot connectors API to index third-party content for search and AI-driven experiences.[78][79]
Common Use Cases and Examples
Microsoft Graph enables developers to build applications that integrate seamlessly with Microsoft 365 services, supporting a variety of practical scenarios across productivity, collaboration, and data management. One prominent use case involves creating notification bots that synchronize email data to Microsoft Teams channels, allowing teams to receive real-time updates from Outlook without leaving their collaboration environment. For instance, an application can monitor incoming emails using delta queries on the mail endpoint and then post formatted notifications to a specified Teams channel. This approach leverages the unified API to bridge communication tools, enhancing workflow efficiency in enterprise settings.[39][27]
To implement such a bot, developers can use a POST request to the /teams/{id}/channels/{id}/messages endpoint, incorporating email subject, sender, and body details into the message payload. The following example demonstrates posting a message derived from email data:
[POST](/page/Post) https://graph.microsoft.com/v1.0/teams/{team-id}/channels/{channel-id}/messages
Content-Type: application/json
{
"body": {
"contentType": "html",
"content": "<p>New [email](/page/Email) from [email protected]: <strong>[Subject](/page/Subject)</strong> - [Email](/page/Email) body summary</p>"
}
}
[POST](/page/Post) https://graph.microsoft.com/v1.0/teams/{team-id}/channels/{channel-id}/messages
Content-Type: application/json
{
"body": {
"contentType": "html",
"content": "<p>New [email](/page/Email) from [email protected]: <strong>[Subject](/page/Subject)</strong> - [Email](/page/Email) body summary</p>"
}
}
This integration requires appropriate permissions such as ChannelMessage.Send, and it supports adaptive cards for richer notifications.
Another key application is developing analytics dashboards that aggregate and visualize user activity insights, helping administrators monitor engagement and productivity trends across an organization. By querying the /users/{id}/insights/trending endpoint with delta queries, applications can efficiently track changes in trending documents or files that users have accessed but not yet viewed, providing data for dashboards that highlight collaborative patterns. Delta queries ensure only incremental updates are fetched, reducing API calls and bandwidth usage for large-scale deployments.[27]
An example delta query for trending insights might look like this:
GET https://graph.microsoft.com/v1.0/users/{user-id}/insights/trending?$delta
GET https://graph.microsoft.com/v1.0/users/{user-id}/insights/trending?$delta
The response includes trending resources with metadata like last modified time, enabling dashboards to display visualizations such as top trending files per user or department. Permissions like Insights.Read.All are necessary for accessing these insights.
File sharing in mobile applications represents a straightforward yet powerful use case, where developers can create secure sharing links for OneDrive or SharePoint files directly within iOS or Android apps. This allows users to generate view or edit links on-the-fly, facilitating quick collaboration without email attachments or complex permission setups. The /drives/{id}/items/{id}/createLink endpoint supports various link types, such as anonymous or organization-specific, ensuring compliance with access policies.[80]
Here's a sample request to create an edit link:
POST https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{item-id}/createLink
Content-Type: [application/json](/page/JSON)
{
"type": "edit",
"scope": "anonymous"
}
POST https://graph.microsoft.com/v1.0/drives/{drive-id}/items/{item-id}/createLink
Content-Type: [application/json](/page/JSON)
{
"type": "edit",
"scope": "anonymous"
}
The response provides the sharing URL and expiration details, which the mobile app can present to users. This scenario is commonly implemented using Microsoft Graph SDKs for iOS (Swift) and Android (Java/Kotlin) to handle authentication and API calls in personal productivity apps.[80]
Cross-platform integrations further extend these capabilities; for example, iOS and Android apps can incorporate Graph APIs to build personal productivity tools that access calendars, tasks, and files across devices, while Power Automate flows utilize Graph triggers to automate workflows like notifying users of new shared files. In Power Automate, triggers such as "When a file is created" in OneDrive can invoke Graph actions to process and route data, streamlining repetitive tasks.[81]
To optimize performance in these scenarios, developers should employ query parameters like $select to retrieve only necessary properties in responses, minimizing payload size and parsing overhead—for instance, selecting just id, name, and webUrl from a drive item list. Additionally, JSON batching allows combining up to 20 requests into a single HTTP call, which is particularly efficient for operations involving multiple endpoints, such as fetching user insights and posting updates simultaneously, thereby reducing latency and throttling risks.[82][83]
Integrations with Microsoft Ecosystem
Microsoft Graph serves as a unified API gateway that enables seamless integration across the Microsoft ecosystem, allowing developers to access and synchronize data from various services without managing multiple endpoints. This connectivity fosters intelligent applications that leverage productivity tools, identity management, analytics, and AI capabilities within the Microsoft stack. By providing standardized access to resources like user profiles, files, emails, and activities, Microsoft Graph facilitates data flow that enhances user experiences and operational efficiency.[1]
Within Microsoft 365, Microsoft Graph maintains deep ties to core services such as Outlook, Teams, and OneDrive, enabling smooth data interchange for collaborative workflows. For instance, the API allows applications to read and manage email messages and calendars in Outlook mailboxes, supporting both personal and shared inboxes to automate notifications or event scheduling. Similarly, integration with Teams provides access to chats, channels, and calls, permitting the creation of bots or extensions that interact with team resources in real time. OneDrive connectivity supports file operations, including uploading, sharing, and searching documents, which streamlines content management across personal and organizational drives. These integrations ensure that data remains synchronized, reducing silos and enabling features like cross-app notifications.[84][39][33]
Microsoft Graph integrates closely with Azure services, particularly Microsoft Entra ID for identity management and Microsoft Fabric for advanced analytics. Through Entra ID APIs, developers can manage users, groups, and applications programmatically, including tasks like user provisioning, role assignments, and authentication flows, which underpin secure access across the ecosystem. For analytics, Microsoft Graph Data Connect allows the secure export of bulk datasets from Microsoft 365 to Microsoft Fabric, Azure Synapse, or Azure Data Factory, enabling organizations to perform large-scale data processing and derive insights on user productivity or collaboration patterns without compromising privacy. This setup supports compliance with data residency requirements while powering business intelligence scenarios.[85][77]
In Dynamics 365 and the Power Platform, Microsoft Graph provides pathways to access customer relationship management (CRM) data and build extensible low-code applications. Beta APIs in Microsoft Graph enable direct interaction with Dynamics 365 Business Central resources, such as companies, customers, and sales orders, allowing custom integrations for ERP workflows. Within Power Apps, developers utilize Graph connectors and SDKs to incorporate Microsoft 365 data into canvas or model-driven apps, facilitating scenarios like embedding user calendars or file attachments without custom coding. Power Automate flows can trigger on Graph events, automating CRM updates based on email or team activities, thus bridging sales, service, and productivity tools.[86]
For Windows and devices, Microsoft Graph's activity feed APIs support cross-device synchronization, particularly through Windows Timeline, by tracking and resuming user activities like document views or app interactions. These APIs allow applications to publish user activities to the graph, which then propagate to compatible devices, enabling users to pick up tasks seamlessly on desktops, mobiles, or web interfaces integrated with Windows experiences. This enhances productivity by maintaining context across hardware, such as resuming a Teams call or OneDrive edit from the last active session.[87]
Microsoft Graph extends to Copilot and AI services via dedicated connectors that ingest external or organizational data into the graph for enhanced model capabilities. Copilot connectors enable the indexing of unstructured data from third-party sources or Microsoft 365 into Microsoft Graph's semantic index, allowing AI agents in Microsoft 365 Copilot to reference this information for grounded responses, such as summarizing files or generating insights from emails. Custom plugins built on Graph APIs further allow developers to extend Copilot Studio agents with real-time data access, supporting use cases like personalized recommendations or automated content creation while adhering to enterprise security policies.[78]
Differences from Legacy APIs
Microsoft Graph represents a significant evolution from the fragmented legacy APIs that preceded it, such as the Office 365 APIs, Azure AD Graph, and Outlook REST API, by providing a unified, REST-based interface for accessing data across Microsoft 365 services. Unlike the Office 365 APIs, which required developers to manage separate endpoints for services like mail, calendar, and contacts—often leading to duplicated authentication and inconsistent data models—Microsoft Graph consolidates these into a single API endpoint, enabling seamless cross-service queries and reducing integration complexity.[1][88] This unification allows for richer scenarios, such as combining email data with user profiles or files, which were not natively supported in the siloed legacy APIs. Additionally, Graph introduces built-in intelligence features, like semantic indexing for search and insights from Microsoft 365 analytics, that extend beyond the basic data retrieval of the original Office 365 APIs.[1]
In contrast to Azure AD Graph, which was specifically designed for directory management in Azure Active Directory and retired on August 31, 2025, after a phased deprecation starting in September 2024, Microsoft Graph adopts a more consistent identity model aligned with Microsoft Entra ID (formerly Azure AD).[10][16] Azure AD Graph used Pascal-cased resource names and limited query capabilities, whereas Graph employs camel-cased resources, supports advanced OData queries (e.g., filtering, expansion, and aggregation), and integrates broader Entra features like B2C consumer identities and conditional access policies that were absent or underdeveloped in the legacy API.[89][90] Permissions in Graph are more granular and least-privilege oriented, often requiring fewer broad scopes for similar tasks compared to Azure AD Graph's coarser model, enhancing security and compliance.[91] Property mappings also differ; for instance, Azure AD Graph's "displayName" directly translates to Graph's equivalent, but some attributes like "provisionedPlans" have no one-to-one match and require alternative approaches.[92]
The Outlook REST API v2.0, deprecated and fully decommissioned on March 31, 2024, has been entirely supplanted by Microsoft Graph for mail, calendar, and contacts operations, offering broader contextual access that the legacy API lacked.[93] While the Outlook REST API was limited to Exchange Online data with separate OAuth scopes and no cross-tenant support, Graph enables unified queries across mailboxes, calendars, and other Microsoft 365 resources, such as retrieving events alongside OneDrive files.[94] This migration supports richer integrations, like embedding calendar data in Teams bots, which were infeasible with the isolated REST endpoints.[95]
Migrating to Microsoft Graph from these legacy APIs yields key benefits, including a drastic reduction in endpoints—from dozens of service-specific ones to a single, versioned API (v1.0 for production and beta for previews)—and improved scalability through JSON-based payloads and efficient batching.[10][1] Developers benefit from consistent authentication via Microsoft Entra ID OAuth 2.0, eliminating the need for multiple credential systems, and enhanced resilience with features like delta queries for change tracking.[96] Post-2024, new applications must use Graph exclusively, as legacy APIs like Azure AD Graph and Outlook REST are no longer supported, ensuring access to ongoing innovations in Microsoft 365.[97] However, limitations persist: certain legacy features, such as Azure AD Graph's specific directory roles or Outlook REST's custom extended properties on events, lack direct equivalents in Graph and require workarounds like custom schema extensions or alternative resource models.[89][98] For example, persisting legacy extended MAPI properties may involve mapping to Graph's open extensions, potentially increasing development effort during transitions.