msgraph-sdk-python

msgraph-sdk is Microsoft’s official Python client for Microsoft Graph, the unified REST API that fronts Entra ID, Outlook, Teams, SharePoint, OneDrive, Intune, and the rest of Microsoft 365. Instead of hand-writing requests against Graph’s sprawling OpenAPI surface, the SDK generates a fluent request-builder tree from that spec via the Kiota code generator, so every endpoint, query parameter, and response model shows up as a discoverable, typed Python object.

The client is async-first (built on asyncio/anyio/trio-compatible coroutines) and delegates authentication entirely to Azure Identity credential classes, letting an app pick the auth flow — client secret, device code, interactive browser, or on-behalf-of — that fits its permission model. Because the request builders, models, and serializers are regenerated straight from Graph’s schema on every release, the library tracks the API’s constant growth without a human maintaining hundreds of endpoint wrappers by hand.

What You Get

• GraphServiceClient - a single root client whose properties (.users, .groups, .me, .teams, …) expose the entire Graph v1.0 surface as typed request builders
• Fluent path navigation - resource paths like /users/{id}/messages become chained Python calls (client.users.by_user_id(id).messages.get()) with compile-time-checked arguments
• Generated typed models - every Graph entity and complex type (User, Message, DriveItem, etc.) ships as a dataclass-like model with JSON/text/form/multipart serializers
• Pluggable Azure Identity auth - works with any TokenCredential/AsyncTokenCredential (ClientSecretCredential, DeviceCodeCredential, InteractiveBrowserCredential, etc.)
• Built-in OData pagination - odata_next_link handling for iterating result sets larger than the default 100-row page
• Structured error handling - failed calls raise a typed APIError carrying the OData error payload instead of a generic HTTP exception

Common Use Cases

• Daemon/background services - a scheduled job uses ClientSecretCredential with application permissions to sync users, groups, or licenses without an interactive sign-in
• Signed-in user apps - a desktop or web app uses DeviceCodeCredential or InteractiveBrowserCredential with delegated scopes to read the current user’s mail, calendar, or files via /me
• Directory and identity automation - provisioning scripts create/update users, groups, and directory roles against Entra ID through the .users, .groups, and .directory_roles builders
• Microsoft 365 data integration - internal tools pull Teams messages, SharePoint sites, or OneDrive DriveItems into another system for search, reporting, or backup
• Security and compliance tooling - scripts query the .security and .identity_protection builders to pull alerts, risky sign-ins, or audit data for a SIEM pipeline

Under The Hood

Architecture The package splits into a thin hand-written layer (msgraph/graph_service_client.py, msgraph/graph_request_adapter.py) and a massive generated tree (msgraph/generated/) mirroring Graph’s OpenAPI description one-to-one: every resource path becomes a *RequestBuilder class exposing typed .get()/.post()/.patch()/.delete() coroutines and child builders reached by properties like .by_user_id(id). GraphServiceClient extends a generated BaseGraphServiceClient and wires in a GraphRequestAdapter, which in turn is built on the shared kiota_abstractions/kiota_authentication_azure runtime shared across all Kiota-generated Microsoft SDKs. Because request execution, serialization, and path building are all delegated to that shared Kiota runtime rather than reimplemented per-endpoint, the thousands of generated request-builder files stay declarative and consistent, and the same architecture is reused verbatim across Microsoft’s other language SDKs.

Tech Stack Built for Python 3.10+ using flit_core as the build backend. Core runtime dependencies are azure-identity for credential handling and four microsoft-kiota-serialization-* packages (json/text/form/multipart) plus msgraph_core for shared request-adapter and batch-request behavior. There is no web framework or database layer — this is purely an outbound API client, so the stack is auth (azure-identity) plus the Kiota abstraction layer, with mypy, pylint, yapf, and isort as the dev-time tooling declared in pyproject.toml.

Code Quality No test suite ships in this repository — CI (.github/workflows/build.yml) runs pylint across msgraph on a matrix of Python 3.10-3.14 plus a validate-public-api-surface workflow that diffs the generated API surface against the source OpenAPI description, rather than exercising behavior with pytest. Correctness is instead enforced upstream at code-generation time (the OpenAPI description plus the Kiota generator), and mypy.ini scopes strict type-checking to msgraph while explicitly ignoring errors inside msgraph.generated given its generated-code volume. Naming and formatting are enforced by pylint, yapf, and isort configs checked into the repo.

What Makes It Unique Rather than a human-maintained wrapper around Graph’s REST API, essentially the entire client — request builders, models, serializers — is regenerated from Microsoft Graph’s OpenAPI description on a recurring release cadence (70+ releases so far), so new Graph endpoints and fields appear in the SDK automatically instead of waiting on a maintainer to hand-write bindings. The fluent path-to-object mapping (URL segments become chained typed method calls) and the shared Kiota runtime across languages are the same generation pipeline Microsoft uses for its other Graph SDKs (.NET, Java, Go, TypeScript), giving consistent behavior across ecosystems rather than an independent one-off implementation.