Microsoft Graph Python SDK

The SDK supports both sync and async credential classes from azure.identity. Your choice depends on the permission type required:

Application Permissions

Used for daemon apps or background tasks without a signed-in user. Use azure.identity.aio.ClientSecretCredential for async application access.

Delegated Permissions (Scopes)

Used when an app requires a user to log in and interact with their own data. Common libraries include:

• DeviceCodeCredential: For environments where authentication is triggered on one machine and completed on another (e.g., cloud servers).
• InteractiveBrowserCredential: For environments with a browser where the user enters credentials manually.
• AuthorizationCodeCredentials: For custom client applications where the frontend calls the backend.

The msgraph-sdk replaces raw URL strings used in msgraph-core with a fluent interface. This allows for method chaining and IDE autocomplete to navigate the Microsoft Graph resource hierarchy. Note that all requests return a coroutine and must be awaited or run in an async loop.

# msgraph-core (Legacy)
resp = client.get('/users/userId/messages')

# msgraph-sdk (New)
req = client.users.by_user_id('userId').messages.get()
resp = asyncio.run(req)

To use the Microsoft Graph SDK, you must first create a credential object using azure.identity and then pass it to the GraphServiceClient.

For application-level access (daemon services), use ClientSecretCredential. For user-level access or local development, you can use AzureCliCredential (requires az login to be performed beforehand).

import asyncio
from azure.identity import ClientSecretCredential
from msgraph import GraphServiceClient

# Create a credential object
credential = ClientSecretCredential(
    tenant_id='TENANT_ID',
    client_id='CLIENT_ID',
    client_secret='CLIENT_SECRET'
)
scopes = ['https://graph.microsoft.com/.default']

# Create the API client
client = GraphServiceClient(credentials=credential, scopes=scopes)

Install the SDK using pip. Note that this is a large package and may take a few minutes. The library requires Python 3.10 or higher.

pip install msgraph-sdk

If you are migrating from the legacy msgraph-core package to the modern msgraph-sdk, note that the SDK introduces a fluent request builder pattern, strongly typed model classes, and requires an asynchronous execution environment. The SDK is built on the Kiota client generator and targets the Microsoft Graph v1.0 API.

# msgraph-core
pip install msgraph-core

# msgraph-sdk
pip install msgraph-sdk

By default, the SDK returns a maximum of 100 rows. If more data is available, the response will contain an odata_next_link. Use the .with_url() method to fetch subsequent batches.

# Initial request
members = await client.groups.by_group_id(group_id).members.get()

# Iterate over result batches using odata_next_link
while members is not None and members.odata_next_link is not None:
    members = await client.groups.by_group_id(group_id).members.with_url(members.odata_next_link).get()
    if members:
        for member in members.value:
            print(member.display_name)

To use the Microsoft Graph SDK, you must first create a credential object using azure.identity and then initialize the GraphServiceClient. For application-level access (client credentials flow), use ClientSecretCredential with your tenant_id, client_id, and client_secret. You must also define the scopes, typically using the default Graph scope: ['https://graph.microsoft.com/.default'].

import asyncio
from azure.identity import ClientSecretCredential
from msgraph import GraphServiceClient

# Create a credential object. Used to authenticate requests
credential = ClientSecretCredential(
    tenant_id='TENANT_ID',
    client_id='CLIENT_ID',
    client_secret='CLIENT_SECRET',
)
scopes = ['https://graph.microsoft.com/.default']

# Create an API client with the credentials and scopes
client = GraphServiceClient(credentials=credential, scopes=scopes)

To create a default Microsoft Graph client, provide an authentication credential (from azure.identity) and the required scopes to the GraphServiceClient constructor. This client uses https://graph.microsoft.com as the base URL and a default HTTPX client.

from azure.identity import AuthorizationCodeCredential
from msgraph import GraphServiceClient

credentials = AuthorizationCodeCredential(
    tenant_id='your_tenant_id',
    client_id='your_client_id',
    authorization_code='your_auth_code',
    redirect_uri='your_redirect_uri'
)
scopes = ['User.Read', 'Mail.ReadWrite']
client = GraphServiceClient(credentials=credentials, scopes=scopes)

The msgraph-sdk uses an AuthenticationProvider to manage token lifecycle (fetching, caching, and refreshing). You should use the AzureIdentityAuthenticationProvider from the kiota-authentication-azure package, which requires an asynchronous credential from azure.identity.aio.

# msgraph-sdk approach
from azure.identity.aio import ClientSecretCredential
from kiota_authentication_azure.azure_identity_authentication_provider import AzureIdentityAuthenticationProvider

credential = ClientSecretCredential(tenant_id='...', client_id='...', client_secret='...')
auth_provider = AzureIdentityAuthenticationProvider(credential)

If you need to provide a custom HTTP client (e.g., for custom proxy settings or timeouts), use GraphClientFactory to create an adapter and pass it to the GraphServiceClient.

import httpx
from msgraph import GraphRequestAdapter
from msgraph_core import GraphClientFactory

# Assuming auth_provider is already defined
http_client = GraphClientFactory.create_with_default_middleware(client=httpx.AsyncClient())
request_adapter = GraphRequestAdapter(auth_provider, http_client)
client = GraphServiceClient(request_adapter=request_adapter)