EXPLAINER

Microsoft Graph API

Microsoft Graph is the REST API for Microsoft 365: users, groups, mail, files, sites, calendars and Teams. You call https://graph.microsoft.com with an Entra ID access token and the scopes an admin has consented.

Short answer: Microsoft Graph is the one REST API in front of Microsoft 365 data. Call graph.microsoft.com with an Entra ID token. It is not a replacement for SPFx UI, and it is not Azure Resource Manager.

What it is

Microsoft Graph is a single REST API at https://graph.microsoft.com that fronts many Microsoft 365 services. Instead of a different base URL for mail, files and directory objects, you call one host with a version prefix (/v1.0 or /beta) and a resource path. /me is the signed-in user. /users/{id}/messages is mail. /sites/{id}/drives is SharePoint or OneDrive file storage. /teams is Teams.

Graph is an API, not a UI framework. SharePoint web parts are still SPFx. Provisioning virtual machines is Azure Resource Manager, not Graph. Mixing those up leads people to hunt for a Graph endpoint that does not exist.

Why and when it is used

Use Graph when your application must read or change tenant data on behalf of a user or, more rarely, as a background service. Examples: list the files in the user's OneDrive, post a channel message, read a calendar to propose meeting times, or sync group membership into your own app.

Do not use Graph as a private database for data Microsoft does not own. Your orders, game state or embeddings belong in your database. Do not screen-scrape the Microsoft 365 portals. And do not call Graph from a browser with a long-lived secret. Public clients use delegated auth; secrets stay on a server.

How it works

You register an app in Entra ID. The user (or an admin) consents to scopes such as Files.Read or Mail.Read. Your app obtains an OAuth 2.0 access token whose audience is Graph, then sends Authorization: Bearer <token>. Graph evaluates the token, the consented scopes, and the user's own permissions on the mailbox or site. A manager cannot read a colleague's mail just because the app has Mail.Read delegated; delegated access is the intersection of the scope and what that user can already do.

Application permissions are different: the app itself is granted access, often tenant-wide, with no signed-in user. That fits daemons and is dangerous if over-scoped. Responses are JSON. Large lists use @odata.nextLink. Changes over time use delta queries so you do not re-download everything. Throttling returns 429 with a Retry-After hint.

Technologies and dependencies

Graph depends on Entra ID tokens (OAuth 2.0, often with OpenID Connect for sign-in). SDKs exist, but the HTTP contract is the stable thing to understand: GET to read, POST to create, PATCH to update, DELETE to remove. Prefer /v1.0 for production. /beta changes and can break.

From SPFx, use the provided Graph client rather than prompting the user for a second login. From a Node or Python service, use a confidential client with a certificate, not a password sitting in source. Teams apps often call Graph for the data behind a tab or bot.

How to get started

  1. Register an app and add delegated User.Read.
  2. Complete an auth-code login and store the access token only in memory on the server (or use a library that refreshes it).
  3. GET https://graph.microsoft.com/v1.0/me and print the display name.
  4. Use Graph Explorer (a Microsoft web tool) to try the next call while signed into the same tenant. It shows the exact permission a call needs.
  5. Add one real resource: GET /me/drive/root/children or a site you know.
  6. Handle 401 (token), 403 (consent or user rights) and 429 (throttle) as different bugs.
  7. Check paging. If you ignore @odata.nextLink you will silently process a partial list.

Write down the scopes you request next to the feature that needs them. Removing a scope later is a migration; adding tenant-wide application permissions "just to try" is how apps get blocked by security review.

Cautions and trade-offs

Graph is broad, so it is easy to ask for *.ReadWrite.All and ship it. Reviewers should reject that. Beta endpoints are tempting because a field exists only there; wrap them and expect breakage. Delta tokens expire and must be renewed. Some SharePoint operations still live on SharePoint REST (/_api) rather than Graph; check before you build a design that assumes Graph parity.

Tokens are not API keys. They expire in about an hour and are scoped. Caching a bearer token in a browser localStorage for a confidential app is a leak. Log request ids when you call support, but do not log the token or the full body of a mailbox. Respect tenant boundaries: a multi-tenant app must store data per tenant and assume an admin will revoke consent.