Microsoft Graph API basics

The Microsoft Graph API is the single REST endpoint for accessing almost everything in Microsoft 365 programmatically. Users, groups, mail, calendars, files, Teams chats, Planner tasks, Intune devices, security alerts, audit logs — all of it lives behind https://graph.microsoft.com/v1.0/ and /beta/.

The shape of the API

Every Graph request looks roughly like:

GET https://graph.microsoft.com/v1.0/users/{id}/messages?$top=10
Authorization: Bearer {access-token}

Common patterns:

• Hierarchical URLs — /users/{id}/mail/folders/{folderId}/messages mirrors the conceptual hierarchy of the data.
• OData query options — $select, $filter, $expand, $top, $skip, $orderby for narrowing and shaping responses.
• $select is especially important — by default Graph returns a default property set; specify exactly the fields you need.
• @odata.nextLink paginates long result sets.
• Delta queries — /delta endpoints let you sync changes incrementally rather than re-pulling everything.

Authentication

Graph requires an OAuth 2.0 access token from Microsoft Entra ID, with one of two permission types:

• Delegated permissions — the app acts on behalf of a signed-in user. The token reflects what the user can do.
• Application permissions — the app acts on its own (no signed-in user). Used for backend services. Requires admin consent.

Each permission scope (e.g., Mail.Read, User.ReadWrite.All, Sites.FullControl.All) is documented per endpoint. Always request the least-privileged scope that satisfies the use case.

The SDKs

Microsoft publishes SDKs for .NET, JavaScript / TypeScript, Java, Python, PHP, Go, and PowerShell. They handle token acquisition, retry, pagination, and typed responses. For ad-hoc exploration, Graph Explorer at developer.microsoft.com/graph/graph-explorer is the best learning environment — sign in, run requests, see permission requirements, copy code snippets.

Common gotchas

• Throttling: Graph rate-limits aggressively. Implement exponential backoff and respect Retry-After.
• /beta is unstable — features there can change without notice. Use /v1.0 for production.
• Some permissions require admin consent even for delegated scenarios — surface this in your app's setup.
• Audit your app's permissions at entra.microsoft.com → Enterprise applications. Over-permissioned apps are an attack surface.

For any non-trivial Microsoft 365 integration — provisioning users, exporting data, automating tasks, building Copilot extensions — Microsoft Graph is the right starting point.