@kody/microsoft
Microsoft 365 helpers for Outlook, Calendar, To Do, OneDrive, and Teams.
Files
@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.
- Open Azure app registrations → New registration.
- Name the app (for example
Kody Microsoft Graph). - 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.
- Accounts in any organizational directory and personal Microsoft accounts → tenant
- Platform: Web. Redirect URI (exact match, no trailing slash):
https://kody.codes/connect/oauth. - Certificates & secrets → New client secret. Copy the Value once.
- 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.
- Always:
- For work/school tenants, an admin may need to Grant admin consent for Teams/
ChannelMessage.Read.Alland some org-restricted mail/file permissions. Personal Microsoft accounts cannot use admin-only permissions. - 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) withpkce=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:
integrationwins (exact Kody OAuth name, e.g.microsoft-work)account: 'work'→microsoft-workaccount: '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 for import paths, smoke checks, and
mutation snippets.
Done when
- OAuth
microsoftis connected; hostgraph.microsoft.comis approved - Smoke test returns
{ ok: true, integration, id, displayName, … }(no mail send / calendar write) - Mutations preview with
dryRun: trueand only run live withconfirm: trueafter 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