Microsoft Graph API Integration

Microsoft Graph API is a RESTful web API that provides a single endpoint to access data and intelligence across Microsoft 365, Azure Active Directory, and other Microsoft cloud services. Before Graph, developers had to use separate APIs for Azure AD (Azure AD Graph), Outlook (Exchange Web Services), SharePoint (CSOM), and others—each with different authentication, request/response formats, and endpoint URLs. Graph unifies these under https://graph.microsoft.com/v1.0 (or /beta for preview features).

All requests to Microsoft Graph require authentication via OAuth 2.0. The flow typically involves: - App Registration: In Azure AD, you register your application (app registration), which generates a Client ID (Application ID) and optionally a Client Secret or certificate. - Permissions Scopes: You configure required permissions (e.g., User.Read, Mail.Send). These can be delegated (on behalf of a signed-in user) or application-only (daemon/service). - Token Acquisition: Your app obtains an access token from the Azure AD token endpoint (https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token). For delegated permissions, use the authorization code flow or implicit flow; for app-only, use client credentials flow. - API Call: The access token is included in the Authorization: Bearer header of requests to https://graph.microsoft.com/v1.0/{resource}. - Response: Graph returns JSON responses. For collections, the response includes @odata.nextLink for pagination.

To register an app and get tokens using Azure CLI:

# Register app
az ad app create --display-name "MyGraphApp" --sign-in-audience AzureADMyOrg

# Get Client ID and Tenant ID
az ad app list --display-name "MyGraphApp" --query "[].appId"

# Create client secret
az ad app credential reset --id <appId> --append --years 2

# Get access token using client credentials flow (app-only)
az account get-access-token --resource https://graph.microsoft.com --query accessToken -o tsv

For delegated flows, use MSAL libraries (e.g., MSAL.NET, MSAL.js). Example token acquisition in C#:

using Azure.Identity;
using Microsoft.Graph;

var scopes = new[] { "https://graph.microsoft.com/.default" };
var clientSecretCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
var graphClient = new GraphServiceClient(clientSecretCredential, scopes);
var user = await graphClient.Users["user@domain.com"].Request().GetAsync();

Graph API integrates with: - Azure AD: User, group, and device management. - Outlook/Exchange: Mail, calendar, contacts. - SharePoint/OneDrive: Files, lists, sites. - Teams: Channels, messages, meetings. - Planner: Tasks and plans. - Security: Identity protection alerts, risk events.

Graph also supports webhooks (subscriptions) to receive change notifications, with a validation handshake: Azure AD sends a POST to your notification URL with a validationToken query parameter; your endpoint must respond with that token in the body within 10 seconds (HTTP 200).

Permissions are categorized as: - Delegated: App acts on behalf of signed-in user. Requires user consent or admin consent. - Application: App runs as a background service without a signed-in user. Requires admin consent.

Common permission scopes: - User.Read.All: Read all users' full profiles. - Mail.Send: Send mail as any user. - Files.ReadWrite.All: Read and write all files that the signed-in user can access. - Group.ReadWrite.All: Read and write all groups.

Admin consent can be granted via Azure portal or programmatically using the adminconsent endpoint.

Graph API returns standard HTTP status codes: - 200 OK for success. - 201 Created for resource creation. - 204 No Content for deletion or updates without body. - 401 Unauthorized (invalid/expired token). - 403 Forbidden (insufficient permissions). - 404 Not Found. - 429 Too Many Requests (throttling). Includes Retry-After header.

Error responses contain JSON with error.code and error.message. Common codes: AuthenticationError, Authorization_RequestDenied, Request_BadRequest, ResourceNotFound.

POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={client_id}
&client_secret={client_secret}
&scope=https://graph.microsoft.com/.default

GET https://graph.microsoft.com/v1.0/users
Authorization: Bearer {access_token}

Batch request:

POST https://graph.microsoft.com/v1.0/$batch
Content-Type: application/json
Authorization: Bearer {token}

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "/users"
    },
    {
      "id": "2",
      "method": "GET",
      "url": "/groups"
    }
  ]
}

Response contains ordered responses with status codes and bodies.

First call:

GET https://graph.microsoft.com/v1.0/users/delta
Authorization: Bearer {token}

Response includes @odata.deltaLink for next changes and @odata.nextLink for next page. Subsequent calls use deltaLink to get only changes since last call.

A large enterprise with 50,000 employees uses multiple HR systems. They need to synchronize user profile data (name, email, department) from Azure AD to an on-premises HR database nightly. Using Microsoft Graph API with application permissions (User.Read.All), a background service runs every night. It uses delta queries to fetch only users changed since last sync: first call gets all users and a delta link; subsequent calls use the delta link. This reduces data transfer from 50,000 to a few hundred records daily. The service handles pagination (default 100 per page) and throttling (10,000 requests per 10 minutes). Misconfiguration: if the app lacks User.Read.All, it gets 403. If delta link is not used, full sync takes hours and hits throttling limits. Production considerations: use multi-threading with a retry policy, store delta link in a database, and monitor for failures using Application Insights.

A SaaS company needs to send automated email notifications from a shared mailbox (e.g., support@company.com) using Microsoft Graph Mail.Send permission. The app uses delegated permissions with a service account (user context) to send emails on behalf of that mailbox. The app obtains tokens using the authorization code flow with a stored refresh token. Common issues: the service account must have a valid license; the app must have Mail.Send delegated permission granted by admin; the user (service account) must consent. If the refresh token expires (after 90 days of inactivity), the app must re-authenticate. Production: store refresh tokens securely (e.g., Key Vault), implement token refresh logic, and handle consent revocation.

A company develops a Teams bot that schedules meetings using Microsoft Graph Calendar API. The bot uses delegated permissions (Calendars.ReadWrite, OnlineMeetings.ReadWrite) on behalf of the signed-in user. The bot uses MSAL.js for implicit flow (single-page app) or authorization code flow (server-side). The bot must handle user consent: if a user hasn't consented, the bot redirects to Azure AD consent page. Common pitfalls: using application permissions instead of delegated (would require admin consent and cannot act as user); not handling pagination when listing events; ignoring timezone differences (Graph returns datetime in UTC). Production: implement a consent cache, use delta queries to sync calendar changes, and handle throttling (e.g., 10,000 requests per 10 minutes per app per tenant).