# @kody/microsoft ## Intent One Microsoft Graph helpers package for Kody agents: Outlook mail, Calendar, To Do, OneDrive, and Teams. Centralizes OAuth integration selection, Graph transport, dry-run guards for mutations, and 403/insufficient-scope errors that name the missing delegated permission and the next `/connect/oauth` step. There is no built-in Kody Microsoft OAuth app — every connection is bring-your-own Azure app registration. ## What it does - Read Outlook mail, Calendar, To Do, OneDrive, and Teams data the signed-in user can access - Preview (`dryRun`) or apply (`confirm: true`) mail send, reply drafts, calendar writes, tasks, and Teams messages - Resolve multi-account OAuth via `./accounts` (`microsoft` / `microsoft-*`) - Call uncommon Graph routes with `./request` - Surface insufficient-scope errors with the next reconnect URL ## Prerequisites / setup **OAuth only** (Azure AD / Microsoft Entra ID app registration). Not an API key. Not a bot token. Do not paste Graph access tokens into chat or into `/account/secrets/new`. Client ID and client secret go into the Kody connect form. Tokens are stored as the saved integration's access/refresh secrets. Wrong path (do not use for Graph access tokens): https://kody.codes/account/secrets/new?name=microsoftAccessToken&description=Do%20not%20use.%20%40kody/microsoft%20is%20OAuth-only.%20Connect%20at%20/connect/oauth%20instead.&allowedHosts=graph.microsoft.com&scope=user ### Required hosts - `graph.microsoft.com` (Microsoft Graph) - `login.microsoftonline.com` (token endpoint; Kody includes the token host automatically) ### Agent setup Kody does not ship a platform Microsoft OAuth app. Register your own confidential web app, then connect it. 1. Open [Azure app registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) → **New registration**. 2. Name the app (for example `Kody Microsoft Graph`). 3. Supported account types: - **Accounts in any organizational directory and personal Microsoft accounts** → tenant `common` (default in the connect URLs below). - Work/school only → tenant `organizations`, or a specific tenant ID. - Personal Microsoft accounts only → tenant `consumers`. 4. Platform: **Web**. Redirect URI (exact match, no trailing slash): `https://kody.codes/connect/oauth`. 5. **Certificates & secrets** → **New client secret**. Copy the **Value** once. 6. **API permissions** → **Microsoft Graph** → **Delegated**: - Always: `openid`, `profile`, `email`, `offline_access`, `User.Read` (smoke test). - Outlook mail: `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`. - Calendar: `Calendars.Read`, `Calendars.ReadWrite`. - To Do: `Tasks.Read`, `Tasks.ReadWrite`. - OneDrive: `Files.Read`, `Files.ReadWrite`. - Teams: `Chat.Read`, `Chat.ReadWrite`, `ChatMessage.Send`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Read.All`, `ChannelMessage.Send`. Do not hide these exports when a token is missing a scope. 7. For work/school tenants, an admin may need to **Grant admin consent** for Teams/`ChannelMessage.Read.All` and some org-restricted mail/file permissions. Personal Microsoft accounts cannot use admin-only permissions. 8. While signed in to Kody, open a prefilled connect URL, paste the **Application (client) ID** and **client secret**, then authorize. Redirect URI to register: `https://kody.codes/connect/oauth` ### Connect URLs Smoke test (`User.Read` only): https://kody.codes/connect/oauth?provider=microsoft&authorizeUrl=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fv2.0%2Fauthorize&tokenUrl=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fv2.0%2Ftoken&flow=confidential&pkce=true&scopes=openid+profile+email+offline_access+User.Read&allowedHosts=graph.microsoft.com&apiBaseUrl=https%3A%2F%2Fgraph.microsoft.com%2Fv1.0&dashboardUrl=https%3A%2F%2Fportal.azure.com%2F%23view%2FMicrosoft_AAD_RegisteredApps%2FApplicationsListBlade&extraAuthorizeParams=%7B%22prompt%22%3A%22consent%22%7D All products in this package: https://kody.codes/connect/oauth?provider=microsoft&authorizeUrl=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fv2.0%2Fauthorize&tokenUrl=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fv2.0%2Ftoken&flow=confidential&pkce=true&scopes=openid+profile+email+offline_access+User.Read+Mail.Read+Mail.ReadWrite+Mail.Send+Calendars.Read+Calendars.ReadWrite+Tasks.Read+Tasks.ReadWrite+Files.Read+Files.ReadWrite+Chat.Read+Chat.ReadWrite+ChatMessage.Send+Team.ReadBasic.All+Channel.ReadBasic.All+ChannelMessage.Read.All+ChannelMessage.Send&allowedHosts=graph.microsoft.com&apiBaseUrl=https%3A%2F%2Fgraph.microsoft.com%2Fv1.0&dashboardUrl=https%3A%2F%2Fportal.azure.com%2F%23view%2FMicrosoft_AAD_RegisteredApps%2FApplicationsListBlade&extraAuthorizeParams=%7B%22prompt%22%3A%22consent%22%7D Outlook mail only: https://kody.codes/connect/oauth?provider=microsoft&authorizeUrl=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fv2.0%2Fauthorize&tokenUrl=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fv2.0%2Ftoken&flow=confidential&pkce=true&scopes=openid+profile+email+offline_access+User.Read+Mail.Read+Mail.ReadWrite+Mail.Send&allowedHosts=graph.microsoft.com&apiBaseUrl=https%3A%2F%2Fgraph.microsoft.com%2Fv1.0&dashboardUrl=https%3A%2F%2Fportal.azure.com%2F%23view%2FMicrosoft_AAD_RegisteredApps%2FApplicationsListBlade&extraAuthorizeParams=%7B%22prompt%22%3A%22consent%22%7D Reconnect an existing connection (scope menu / saved endpoints): https://kody.codes/connect/oauth?provider=microsoft A second Microsoft account uses a different `provider` name, for example `microsoft-work`. Pass that name as `integration` (or `account: 'work'`) on every call. Decoded connect settings: - Authorize: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize` - Token: `https://login.microsoftonline.com/common/oauth2/v2.0/token` - Flow: `confidential` (client secret on the token request) with `pkce=true` - Extra authorize params: `{"prompt":"consent"}` so added scopes appear on reconnect - API base: `https://graph.microsoft.com/v1.0` ### Multi-account No hard-coded person or brand aliases. Resolution: - `integration` wins (exact Kody OAuth name, e.g. `microsoft-work`) - `account: 'work'` → `microsoft-work` - `account: 'default'` / `'microsoft'` / omitted → `microsoft` - values that already start with `microsoft-` are used as-is ### Scopes by export | Export | Read scopes | Write / send scopes | | --- | --- | --- | | `smoke-test` | `User.Read` | — | | `mail` | `Mail.Read` | `Mail.ReadWrite`, `Mail.Send` | | `calendar` | `Calendars.Read` | `Calendars.ReadWrite` | | `todo` | `Tasks.Read` | `Tasks.ReadWrite` | | `onedrive` | `Files.Read` | `Files.ReadWrite` | | `teams` chats | `Chat.Read` | `Chat.ReadWrite`, `ChatMessage.Send` | | `teams` joined / channels | `Team.ReadBasic.All`, `Channel.ReadBasic.All` | — | | `teams` channel messages | `ChannelMessage.Read.All` (often admin consent) | `ChannelMessage.Send` | If Graph returns 403, helpers throw `MicrosoftGraphError` with the path, saved integration, likely delegated scope, whether admin consent is likely, and the next `/connect/oauth` reconnect URL. Changing Azure API permissions does not update the current access token — reconnect after every scope change. Agents: see [`AGENTS.md`](./AGENTS.md) for import paths, smoke checks, and mutation snippets. ## Done when - OAuth `microsoft` is connected; host `graph.microsoft.com` is approved - Smoke test returns `{ ok: true, integration, id, displayName, … }` (no mail send / calendar write) - Mutations preview with `dryRun: true` and only run live with `confirm: true` after you approve the exact change ## Branding `community-icon.svg` is Microsoft's four-square mark (red / green / blue / yellow) on a white rounded tile. Paths are unmodified aside from tiling for 56px legibility. Microsoft, Outlook, OneDrive, Teams, and related marks are trademarks of Microsoft Corporation. This package is not affiliated with or endorsed by Microsoft. Share this package as https://kody.codes/@kody/microsoft ## Docs - [Microsoft Graph overview](https://learn.microsoft.com/en-us/graph/overview) - [Azure app registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) - [Microsoft identity platform (OAuth 2.0)](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow) - [Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference)