Microsoft 365 API Patterns

Microsoft Graph fundamentals shared by every M365 skill: Entra token scopes and the per-request Bearer model, OData query operators and filter syntax, @odata.nextLink pagination, delta queries for inc

SKILL.md

GitHub

Microsoft Graph API Patterns

Overview

Microsoft Graph is the unified REST API surface for all M365 services (users, mail, calendar, Teams, OneDrive, security). All M365 MCP tools ultimately make Graph calls. Understanding Graph's OData query syntax, pagination model, throttling behavior, and auth patterns is essential for building reliable M365 workflows.

Anti-triggers

This skill teaches you to compose Graph calls by hand. Two neighbouring plugins cover the same tenant with almost identical vocabulary, and choosing the wrong one is the most common routing mistake in the Microsoft estate:

  • A read-only question about one tenant — "how many users", "who has no MFA registered", "which licences are unassigned". The Graph Enterprise MCP answers these from a vetted query catalogue, so nobody hand-writes a $filter; use the microsoft-graph plugin's microsoft-graph-querying skill. Hand-writing a Graph URL when that server is connected is the exact error pattern it exists to prevent.
  • Anything spanning more than one customer tenant — fleet-wide standards, BPA drift, GDAP, or a packaged action such as offboard / reset MFA / revoke sessions. Use the cipp plugin, which carries the multi-tenant scope and per-tenant audit trail this plugin does not.
  • A tenant that authenticates but returns nothing — that is an app registration and admin-consent problem, not a query-syntax problem; use microsoft-graph-connection.

The short rule: ask one tenant → microsoft-graph; change one tenant → this plugin; do either across the fleet → cipp.

Authentication

Token Scope for MSP Operations

The Softeria MS-365 MCP server (--org-mode) accepts a Bearer token per request via the Authorization header. The token must be obtained from Microsoft Entra using the common endpoint (multi-tenant) with the following scopes:

Scope Purpose
https://graph.microsoft.com/.default All Graph permissions granted to app
openid ID token for tenant ID extraction
profile User profile claims
offline_access Refresh token for session persistence

Base URL

All Graph API calls use:

https://graph.microsoft.com/v1.0/

Beta features (preview, subject to change):

https://graph.microsoft.com/beta/

OData Query Parameters

Parameter Purpose Example
$select Return only specified fields $select=id,displayName,email
$filter Filter results $filter=accountEnabled eq true
$search Full-text search (mailboxes, users) $search="displayName:Smith"
$orderby Sort results $orderby=displayName asc
$top Limit results per page $top=100
$skip Skip N results $skip=100
$count Include total count $count=true
$expand Include related entities $expand=manager

Filter Syntax

eq        equal             $filter=accountEnabled eq true
ne        not equal         $filter=jobTitle ne 'Manager'
gt/lt     greater/less      $filter=createdDateTime gt 2024-01-01T00:00:00Z
ge/le     >=, <=            same but inclusive
and/or    logical           $filter=dept eq 'IT' and accountEnabled eq true
not       negation          $filter=not startsWith(mail,'test')
startsWith prefix match     $filter=startsWith(displayName,'J')
endsWith  suffix match      $filter=endsWith(mail,'@contoso.com')
contains  substring         $filter=contains(jobTitle,'Manager')
any/all   collection ops    $filter=assignedLicenses/any(x:x/skuId eq '<guid>')

Advanced Queries (Require ConsistencyLevel: eventual)

Some filters require the ConsistencyLevel: eventual header and $count=true:

GET /v1.0/users?$filter=assignedLicenses/$count eq 0&$count=true&ConsistencyLevel: eventual

Pagination

Graph uses server-side pagination. Always check for @odata.nextLink in responses.

Standard Pagination Loop

1. Make initial request with $top=100
2. If response contains @odata.nextLink → follow it
3. Repeat until no @odata.nextLink

Response with more pages:

{
  "@odata.context": "...",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$skiptoken=abc123",
  "value": [...]
}

Response — last page:

{
  "@odata.context": "...",
  "value": [...]
}

The Softeria MCP server handles pagination automatically for supported operations.

Delta Queries (Incremental Sync)

Delta queries return only changed items since the last sync — ideal for regular polling.

Initial Delta Request

GET /v1.0/users/delta?$select=id,displayName,userPrincipalName,accountEnabled

Response includes a @odata.deltaLink after the last page — store this.

Subsequent Delta Requests

GET {deltaLink}

Returns only users added, modified, or deleted since the delta token was issued. Deleted users have "@removed": { "reason": "deleted" } in the response.

Throttling and Retry

Graph throttles requests at both per-app and per-tenant levels. Throttled responses return 429 Too Many Requests.

Retry-After Header

Always check the Retry-After header on 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 15

Wait the specified seconds before retrying.

Graph Throttle Limits (Approximate)

Resource Limit
Per app per tenant 10,000 req/10 min
Per user 3,000 req/10 min
Mail search 10 concurrent
Reports 1 req/15 min per report

Best Practices

  1. Use $select to request only needed fields (reduces payload + throttle pressure)
  2. Use $filter server-side rather than fetching all and filtering in code
  3. Use delta queries for sync operations instead of polling all items
  4. Batch unrelated requests (see below) to reduce round-trips

Batch Requests

Combine up to 20 independent Graph calls into one HTTP request:

POST /v1.0/$batch
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "/users/user1@contoso.com?$select=displayName,accountEnabled"
    },
    {
      "id": "2",
      "method": "GET",
      "url": "/users/user2@contoso.com?$select=displayName,accountEnabled"
    }
  ]
}

Response:

{
  "responses": [
    { "id": "1", "status": 200, "body": { "displayName": "Alice", "accountEnabled": true } },
    { "id": "2", "status": 200, "body": { "displayName": "Bob", "accountEnabled": false } }
  ]
}

Use for fetching details on multiple known user IDs simultaneously.

Common Error Codes

HTTP Code Meaning Fix
400 Request_BadRequest Malformed OData filter Check filter syntax
401 InvalidAuthenticationToken Token expired or malformed Re-authenticate
403 Authorization_RequestDenied Missing Graph permission Add scope, re-consent
404 Request_ResourceNotFound Object doesn't exist Check GUID/UPN
429 ActivityLimitReached Throttled Wait Retry-After seconds
500 ServiceInternalServerError Graph outage Retry with backoff
503 ServiceUnavailable Transient Retry with backoff

Useful Graph Explorer

For testing queries interactively: https://developer.microsoft.com/graph/graph-explorer

Log in with a test M365 account to explore API responses before writing code.

Related Skills