About

Microsoft 365 & Microsoft Graph library for Python

Status

📌 Python Requirement: Python 3.8 or newer.

Installation

pip install office365-rest-python-client

Or with uv:

uv pip install office365-rest-python-client

The latest version from GitHub can be installed directly:

pip install git+https://github.com/vgrem/office365-rest-python-client.git

---

Authentication

The library provides two clients: ClientContext for SharePoint REST API and GraphClient for Microsoft Graph API.

📌 ACS Retirement Notice: Azure Access Control Service (ACS) for SharePoint is being retired. ACS stopped working for new tenants on November 1, 2024, and will be fully retired on April 2, 2026. Use Azure AD-based authentication instead. Learn more

ClientContext - SharePoint

Azure AD App-Only (certificate) - RECOMMENDED

ctx = ClientContext('{site_url}').with_client_certificate(tenant, client_id, thumbprint, cert_path)

Docs | Example

Username & password (MSAL ROPC) - RECOMMENDED for user auth

Uses the OAuth 2.0 Resource Owner Password Credentials grant via MSAL.

from office365.sharepoint.client_context import ClientContext

ctx = ClientContext('{site_url}').with_username_and_password(
    tenant='{tenant}', client_id='{client_id}',
    username='{username}', password='{password}'
)

Docs | Example

Interactive

Opens a browser for user login.

from office365.sharepoint.client_context import ClientContext
ctx = ClientContext('{site_url}').with_interactive('{tenant}', '{client_id}')

Prerequisite: configure Redirect URI as http://localhost in Azure Portal.

Docs | Example

Device code

User authenticates on another device via a displayed code.

ctx = ClientContext('{site_url}').with_device_flow('{tenant}', '{client_id}')

Docs | Example

Legacy - SAML User Auth ⚠️

Deprecated: with_user_credentials uses the legacy SAML-based auth flow which is being phased out by Microsoft. Use with_username_and_password (MSAL ROPC OAuth 2.0) instead.

from office365.sharepoint.client_context import ClientContext
ctx = ClientContext('{site_url}').with_user_credentials('{username}', '{password}')

Replaced by:

ctx.with_username_and_password(tenant='{tenant}', client_id='{client_id}', username='{username}', password='{password}')

Docs

Legacy - ACS App-Only ⚠️

Deprecated: Azure ACS is being retired. Use Azure AD certificate auth instead.

from office365.runtime.auth.client_credential import ClientCredential
from office365.sharepoint.client_context import ClientContext
ctx = ClientContext('{site_url}').with_credentials(ClientCredential('{client_id}', '{client_secret}'))

Docs | Example

---

GraphClient - Microsoft Graph

Client secret

Uses the OAuth 2.0 Client Credentials grant via MSAL.

from office365.graph_client import GraphClient
client = GraphClient(tenant='{tenant}').with_client_secret(client_id='{client_id}', client_secret='{client_secret}')

Docs | Example

Certificate

client = GraphClient(tenant='{tenant}').with_client_certificate(client_id, thumbprint, private_key)

Docs | Example

Interactive

Opens a browser for user login.

client = GraphClient(tenant='{tenant}').with_token_interactive(client_id='{client_id}')

Docs

Username & password (MSAL ROPC)

client = GraphClient(tenant='{tenant}').with_username_and_password('{client_id}', '{username}', '{password}')

Docs

Custom token acquisition

Any OAuth2-compliant library (MSAL, ADAL, etc.):

def acquire_token():
    # your token acquisition logic
    return token

client = GraphClient(acquire_token)

---

ClientContext - SharePoint API

Quick start

from office365.sharepoint.client_context import ClientContext

site_url = "https://{tenant}.sharepoint.com"
ctx = ClientContext(site_url).with_username_and_password(
    tenant="{tenant}", client_id="{client_id}",
    username="{username}", password="{password}",
)
web = ctx.web.get().execute_query()
print(f"Web title: {web.title}")

Azure environments

Add the environment parameter for non-global clouds:

from office365.azure_env import AzureEnvironment
ctx = ClientContext('{site_url}', environment=AzureEnvironment.USGovernmentHigh).with_credentials(...)

Examples

For a comprehensive list, see the SharePoint examples guide.

---

GraphClient — Microsoft Graph API

Quick start

from office365.graph_client import GraphClient

client = GraphClient(tenant='{tenant}').with_client_secret(client_id='{client_id}', client_secret='{client_secret}')
me = client.me.get().execute_query()
print(f"User: {me.user_principal_name}")

Outlook

from office365.graph_client import GraphClient
client = GraphClient(tenant='{tenant}').with_client_secret(client_id='{client_id}', client_secret='{client_secret}')
client.me.send_mail(
    subject="Meet for lunch?",
    body="The new cafeteria is open.",
    to_recipients=["user@contoso.onmicrosoft.com"]
).execute_query()

Send email | List messages | Download | Search

More Outlook examples.

OneDrive

from office365.graph_client import GraphClient
client = GraphClient(tenant='{tenant}')
drives = client.drives.get().execute_query()
for drive in drives:
    print(f"Drive url: {drive.web_url}")

Download files | Upload files | List drives

More OneDrive examples.

Teams

from office365.graph_client import GraphClient
client = GraphClient(tenant='{tenant}')
new_team = client.groups["{group_id}"].add_team().execute_query()

Create a team | List teams | Send messages

More Teams examples.

OneNote

from office365.graph_client import GraphClient
client = GraphClient(tenant='{tenant}')
with open("./MyPage.html", 'rb') as f:
    page = client.me.onenote.pages.add(presentation_file=f).execute_query()

Planner

from office365.graph_client import GraphClient
client = GraphClient(tenant='{tenant}')
task = client.planner.tasks.add(title="New task", planId="--plan-id--").execute_query()

---

Third Party Libraries

The following libraries will be installed when you install the client library:

• requests
• Microsoft Authentication Library (MSAL) for Python