# 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:

```env
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

```http
GET  /health
GET  /version
GET  /microsoft365/status
GET  /microsoft365/users?top=25&search=jane
GET  /microsoft365/users/{user_id}
GET  /microsoft365/users/{user_id}/mail/messages?folder=Inbox&top=25
POST /microsoft365/users/{user_id}/mail/send
GET  /microsoft365/users/{user_id}/calendar/events?top=25
POST /microsoft365/users/{user_id}/calendar/events
GET  /microsoft365/users/{user_id}/drive/root/children?top=25
PUT  /microsoft365/users/{user_id}/drive/root/{path}
GET  /microsoft365/groups?top=25
GET  /microsoft365/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

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

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