Microsoft Graph SDK
Implement Microsoft Graph access with the current language SDK, the right authentication flow, least-privilege permissions, pagination, retry handling, and resource-specific patterns.
When to invoke
- "Add Microsoft Graph SDK to this app."
- "Call Graph to read users, mail, calendar, Teams, files, or SharePoint data."
- "Choose the right Graph authentication flow for this service."
- "Handle Graph paging, throttling, batching, or delta sync."
- "Fix Microsoft Graph 403, 429, subscription, or permission issues."
Progressive disclosure and bundled resources
| Reference |
Use when |
references/dotnet.md |
Project contains .cs, .csproj, .sln, or user asks for C#/.NET. |
references/typescript.md |
Project contains package.json, .ts, .js, or user asks for Node.js/browser. |
references/python.md |
Project contains .py, pyproject.toml, requirements.txt, or user asks for Python. |
Read the language reference before writing SDK-specific code.
Language and documentation selection
- Determine the target language from files or user request.
- If multiple languages are present, match the files being edited or ask the user.
- Ground implementation in current Microsoft Graph SDK docs and version-specific samples rather than memory.
- Use Graph Explorer to test paths and permissions before coding when feasible.
Authentication decision table
| Scenario |
Flow |
| Background service or daemon with no user |
Client credentials, app-only permissions. |
| Agent or API acting for a signed-in user |
On-Behalf-Of (OBO), delegated permissions. |
| Azure Function, Container App, VM, or Azure-hosted service |
Managed Identity, usually through DefaultAzureCredential. |
| CLI tool or local dev script |
Device code or interactive browser. |
| Browser-only single-page app |
Authorization code + PKCE. |
Never use client credentials when a user context is required. Prefer DefaultAzureCredential in Azure-hosted apps. Never hardcode secrets; use environment variables, Azure Key Vault, Secret Manager, or managed identity.
Core SDK patterns
| Concern |
Rule |
| Client lifetime |
Construct GraphServiceClient once and reuse it. |
| Credentials |
Pass an Azure Identity credential or language-specific auth provider; do not hand-roll raw HTTP auth. |
| Async calls |
Always await SDK calls. |
| Projection |
Use $select to limit returned fields. |
| Filtering |
Use $filter server-side instead of in-memory filtering. |
| Expansion |
Use $expand for small related resources. |
| Pagination |
Check @odata.nextLink and use the SDK PageIterator; set $top when useful. |
| Batching |
Use $batch for up to 20 independent Graph calls; match responses by request id. |
| Delta sync |
Store @odata.deltaLink durably and reuse it for incremental changes. |
| Webhooks |
Create POST /subscriptions, echo validationToken as plain text with HTTP 200, and renew before expirationDateTime. |
| Throttling |
Handle HTTP 429 by honoring Retry-After; avoid uncontrolled fan-out. |
Advanced Graph patterns
| Pattern |
Use when |
Critical detail |
| Delta queries |
Sync users, groups, messages, calendar events, Teams channels, and supported resources incrementally. |
First call such as GET /users/delta returns all items plus @odata.deltaLink; subsequent calls use the link. |
| Change notifications |
Need near-real-time updates. |
Notification URL must be HTTPS; handle lifecycle notifications with notificationUrl and lifecycleNotificationUrl. |
| Resource data notifications |
High-volume scenarios need changed resource payloads. |
Requires additional encryption setup. |
| Retry middleware |
Production workloads may hit 429. |
Enable SDK retry middleware or implement exact Retry-After waits. |
| Least privilege |
Avoid broad permissions. |
Use https://learn.microsoft.com/graph/permissions-reference and admin consent only when required. |
Common resource paths
| Goal |
Resource path |
| Get signed-in user's profile |
GET /me |
| List user's mailbox messages |
GET /me/messages |
| Send an email |
POST /me/sendMail |
| List calendar events |
GET /me/events |
| Get user's OneDrive root |
GET /me/drive/root/children |
| List Teams the user is in |
GET /me/joinedTeams |
| Post a Teams channel message |
POST /teams/{id}/channels/{id}/messages |
| List SharePoint site lists |
GET /sites/{siteId}/lists |
| Search across M365 |
POST /search/query |
| List all users in tenant |
GET /users |
| Get group members |
GET /groups/{id}/members |
Use the SDK fluent API equivalent, for example client.Users[userId].Messages.GetAsync(...) in .NET where appropriate.
Procedure
- Identify target language and read the matching
references/ file.
- Select auth flow from the scenario table and confirm application versus delegated permissions.
- Check Microsoft Graph overview, Graph Explorer, and permissions reference for current endpoint and scope requirements.
- Implement a reused
GraphServiceClient with the language-specific SDK package.
- Add
$select, $filter, pagination, and retry handling from the start.
- For dashboards, consider batching; for synchronization, prefer delta queries; for event-driven workloads, use change notifications.
- Validate 403, 429, subscription, and paging behavior with concrete evidence.
Compatibility terminology
Preserve these baseline terms when they appear in user input, existing files, logs, or migration output; they are included to keep legacy wording, commands, paths, and API names recognizable during execution.
built-indeltaLinkhigh-call-counthigh-volumemail/calendarusers/groups
Output template
## Microsoft Graph SDK result
**Status:** implemented | planned | blocked
**Language:** .NET | TypeScript/JavaScript | Python
**Auth flow:** client credentials | OBO | managed identity | device code | interactive browser | auth code + PKCE
### Permissions
| Operation | Permission | Type | Consent |
| --- | --- | --- | --- |
| `<Graph path>` | `<scope>` | Application/Delegated | <admin/user> |
### Implementation notes
- Client: `GraphServiceClient` reused: <yes/no>
- Pagination: <PageIterator/nextLink handling>
- Throttling: <Retry-After or middleware>
- Validation: <Graph Explorer/test result>
Quality gate
References
1---2name: msgraph-sdk-23description: Integrate Microsoft Graph SDK in .NET, TypeScript/JavaScript, or Python applications using correct authentication, permissions, SDK clients, pagination, batching, delta queries, change notifications, throttling, and Microsoft 365 resource paths. Use when accessing users, mail, calendar, Teams, OneDrive, SharePoint, groups, search, or other Microsoft 365 data through Graph.4---56# Microsoft Graph SDK78Implement Microsoft Graph access with the current language SDK, the right authentication flow, least-privilege permissions, pagination, retry handling, and resource-specific patterns.910## When to invoke1112- "Add Microsoft Graph SDK to this app."13- "Call Graph to read users, mail, calendar, Teams, files, or SharePoint data."14- "Choose the right Graph authentication flow for this service."15- "Handle Graph paging, throttling, batching, or delta sync."16- "Fix Microsoft Graph 403, 429, subscription, or permission issues."1718## Progressive disclosure and bundled resources1920| Reference | Use when |21| --- | --- |22| `references/dotnet.md` | Project contains `.cs`, `.csproj`, `.sln`, or user asks for C#/.NET. |23| `references/typescript.md` | Project contains `package.json`, `.ts`, `.js`, or user asks for Node.js/browser. |24| `references/python.md` | Project contains `.py`, `pyproject.toml`, `requirements.txt`, or user asks for Python. |2526Read the language reference before writing SDK-specific code.2728## Language and documentation selection29301. Determine the target language from files or user request.312. If multiple languages are present, match the files being edited or ask the user.323. Ground implementation in current Microsoft Graph SDK docs and version-specific samples rather than memory.334. Use Graph Explorer to test paths and permissions before coding when feasible.3435## Authentication decision table3637| Scenario | Flow |38| --- | --- |39| Background service or daemon with no user | Client credentials, app-only permissions. |40| Agent or API acting for a signed-in user | On-Behalf-Of (OBO), delegated permissions. |41| Azure Function, Container App, VM, or Azure-hosted service | Managed Identity, usually through `DefaultAzureCredential`. |42| CLI tool or local dev script | Device code or interactive browser. |43| Browser-only single-page app | Authorization code + PKCE. |4445Never use client credentials when a user context is required. Prefer `DefaultAzureCredential` in Azure-hosted apps. Never hardcode secrets; use environment variables, Azure Key Vault, Secret Manager, or managed identity.4647## Core SDK patterns4849| Concern | Rule |50| --- | --- |51| Client lifetime | Construct `GraphServiceClient` once and reuse it. |52| Credentials | Pass an Azure Identity credential or language-specific auth provider; do not hand-roll raw HTTP auth. |53| Async calls | Always `await` SDK calls. |54| Projection | Use `$select` to limit returned fields. |55| Filtering | Use `$filter` server-side instead of in-memory filtering. |56| Expansion | Use `$expand` for small related resources. |57| Pagination | Check `@odata.nextLink` and use the SDK `PageIterator`; set `$top` when useful. |58| Batching | Use `$batch` for up to 20 independent Graph calls; match responses by request `id`. |59| Delta sync | Store `@odata.deltaLink` durably and reuse it for incremental changes. |60| Webhooks | Create `POST /subscriptions`, echo `validationToken` as plain text with HTTP 200, and renew before `expirationDateTime`. |61| Throttling | Handle HTTP 429 by honoring `Retry-After`; avoid uncontrolled fan-out. |6263## Advanced Graph patterns6465| Pattern | Use when | Critical detail |66| --- | --- | --- |67| Delta queries | Sync users, groups, messages, calendar events, Teams channels, and supported resources incrementally. | First call such as `GET /users/delta` returns all items plus `@odata.deltaLink`; subsequent calls use the link. |68| Change notifications | Need near-real-time updates. | Notification URL must be HTTPS; handle lifecycle notifications with `notificationUrl` and `lifecycleNotificationUrl`. |69| Resource data notifications | High-volume scenarios need changed resource payloads. | Requires additional encryption setup. |70| Retry middleware | Production workloads may hit 429. | Enable SDK retry middleware or implement exact `Retry-After` waits. |71| Least privilege | Avoid broad permissions. | Use https://learn.microsoft.com/graph/permissions-reference and admin consent only when required. |7273## Common resource paths7475| Goal | Resource path |76| --- | --- |77| Get signed-in user's profile | `GET /me` |78| List user's mailbox messages | `GET /me/messages` |79| Send an email | `POST /me/sendMail` |80| List calendar events | `GET /me/events` |81| Get user's OneDrive root | `GET /me/drive/root/children` |82| List Teams the user is in | `GET /me/joinedTeams` |83| Post a Teams channel message | `POST /teams/{id}/channels/{id}/messages` |84| List SharePoint site lists | `GET /sites/{siteId}/lists` |85| Search across M365 | `POST /search/query` |86| List all users in tenant | `GET /users` |87| Get group members | `GET /groups/{id}/members` |8889Use the SDK fluent API equivalent, for example `client.Users[userId].Messages.GetAsync(...)` in .NET where appropriate.9091## Procedure92931. Identify target language and read the matching `references/` file.942. Select auth flow from the scenario table and confirm application versus delegated permissions.953. Check Microsoft Graph overview, Graph Explorer, and permissions reference for current endpoint and scope requirements.964. Implement a reused `GraphServiceClient` with the language-specific SDK package.975. Add `$select`, `$filter`, pagination, and retry handling from the start.986. For dashboards, consider batching; for synchronization, prefer delta queries; for event-driven workloads, use change notifications.997. Validate 403, 429, subscription, and paging behavior with concrete evidence.100101## Compatibility terminology102103Preserve these baseline terms when they appear in user input, existing files, logs, or migration output; they are included to keep legacy wording, commands, paths, and API names recognizable during execution.104105- `built-in`106- `deltaLink`107- `high-call-count`108- `high-volume`109- `mail/calendar`110- `users/groups`111112## Output template113114```markdown115## Microsoft Graph SDK result116117**Status:** implemented | planned | blocked118**Language:** .NET | TypeScript/JavaScript | Python119**Auth flow:** client credentials | OBO | managed identity | device code | interactive browser | auth code + PKCE120121### Permissions122| Operation | Permission | Type | Consent |123| --- | --- | --- | --- |124| `<Graph path>` | `<scope>` | Application/Delegated | <admin/user> |125126### Implementation notes127- Client: `GraphServiceClient` reused: <yes/no>128- Pagination: <PageIterator/nextLink handling>129- Throttling: <Retry-After or middleware>130- Validation: <Graph Explorer/test result>131```132133## Quality gate134135- [ ] Target language and matching bundled reference were used.136- [ ] Auth flow matches user-context versus app-only requirements.137- [ ] Permissions are least-privilege and checked against the Microsoft permissions reference.138- [ ] `GraphServiceClient` is constructed once and reused.139- [ ] Collection reads handle `@odata.nextLink` or `PageIterator`.140- [ ] HTTP 429 handling honors `Retry-After`.141- [ ] No secret is hardcoded.142- [ ] Graph paths, SDK calls, and current docs were verified.143144## References145146- [Microsoft Graph overview](https://learn.microsoft.com/graph/overview)147- [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer)148- [Graph permissions reference](https://learn.microsoft.com/graph/permissions-reference)
paulasilvatech