microsoft-365-service/README.md

Microsoft 365 Service

FastAPI service for server-to-server communication with Microsoft 365 through Microsoft Graph.

Configuration

Create an app registration in Microsoft Entra ID, grant the required Microsoft Graph application permissions, and expose these environment variables:

MS365_TENANT_ID=00000000-0000-0000-0000-000000000000
MS365_CLIENT_ID=00000000-0000-0000-0000-000000000000
MS365_CLIENT_SECRET=secret-value
MS365_GRAPH_BASE_URL=https://graph.microsoft.com/v1.0
MS365_GRAPH_SCOPE=https://graph.microsoft.com/.default
MS365_REQUEST_TIMEOUT_SECONDS=30

The service uses the OAuth2 client credentials flow, so Microsoft Graph permissions must be application permissions approved by an administrator.

Implemented Services

• Users: list and read users.
• Mail: list messages and send email, including file attachments.
• Calendar: list and create events, including Teams online meetings.
• OneDrive: list root files and upload small files.
• Groups and Teams: list groups and list team channels.

API

GET  /health
GET  /version
GET  /status
GET  /users?top=25&search=jane
GET  /users/{user_id}
GET  /users/{user_id}/mail/messages?folder=Inbox&top=25
POST /users/{user_id}/mail/send
GET  /users/{user_id}/calendar/events?top=25
POST /users/{user_id}/calendar/events
GET  /users/{user_id}/drive/root/children?top=25
PUT  /users/{user_id}/drive/root/{path}
GET  /groups?top=25
GET  /teams/{team_id}/channels

user_id can be a Microsoft Graph user id or user principal name, for example jane@example.com.

Required Graph Permissions

Grant only the permissions your deployment actually uses:

• Users: User.Read.All
• Mail read: Mail.Read
• Mail send: Mail.Send
• Calendar read/write: Calendars.ReadWrite
• OneDrive read/write: Files.ReadWrite.All
• Groups and Teams channel listing: Group.Read.All, Team.ReadBasic.All, Channel.ReadBasic.All

Run Locally

pip install -r requirements.txt
uvicorn app.main:app --reload

Open http://localhost:8000/docs for the generated OpenAPI UI.