OneNote Reference Architecture
Overview
OneNote notebooks live in three completely different storage backends โ personal OneDrive, SharePoint team sites, and Microsoft 365 Groups โ each with its own Graph API path, permission model, and behavioral quirks. Building an integration that "just works with OneNote" means handling all three locations, because users do not know (or care) where their notebook is stored. The API path /me/onenote/notebooks only returns personal notebooks; SharePoint and Group notebooks require different endpoints entirely. This skill maps the full architecture: storage locations, API paths, the object hierarchy (and its gotchas), and a service abstraction layer that normalizes all three locations into a single interface.
Prerequisites
- Azure AD app registration with delegated permissions (
Notes.ReadWrite minimum)
- Familiarity with Microsoft Graph API URL structure (
https://graph.microsoft.com/v1.0)
- For SharePoint notebooks:
Sites.Read.All or Sites.ReadWrite.All permission
- For Group notebooks:
Group.Read.All or Group.ReadWrite.All permission
- Python:
pip install msgraph-sdk azure-identity or Node: npm install @microsoft/microsoft-graph-client @azure/identity
Instructions
System Architecture
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ Your App โโโโโ>โ MSAL Auth โโโโโ>โ Azure AD โ
โ (Client) โ โ (Delegated) โ โ Token Service โ
โโโโโโโโฌโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ
โ Bearer Token
v
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Microsoft Graph API (v1.0) โ
โ https://graph.microsoft.com/v1.0 โ
โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโค
โ /me/onenote โ /sites/{id}/ โ /groups/{id}/ โ
โ โ onenote โ onenote โ
โโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโผโโโโโโโโโโโโโโโโโโโโโโโโโค
โ Personal โ SharePoint โ Group โ
โ OneDrive โ Document Lib โ Notebook โ
โ Storage โ Storage โ Storage โ
โโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโโโโโโโโ
Three Notebook Locations
1. Personal Notebooks (OneDrive)
GET https://graph.microsoft.com/v1.0/me/onenote/notebooks
GET https://graph.microsoft.com/v1.0/me/onenote/notebooks/{notebook-id}/sections
GET https://graph.microsoft.com/v1.0/me/onenote/sections/{section-id}/pages
- Owned by the signed-in user
- Stored in user's OneDrive root
/Documents/ or /Notebooks/
- Permission:
Notes.ReadWrite (user consent, no admin needed)
- Cannot be shared with external tenants via API
2. SharePoint Site Notebooks
GET https://graph.microsoft.com/v1.0/sites/{site-id}/onenote/notebooks
GET https://graph.microsoft.com/v1.0/sites/{site-id}/onenote/notebooks/{notebook-id}/sections
GET https://graph.microsoft.com/v1.0/sites/{site-id}/onenote/sections/{section-id}/pages
-
Owned by the SharePoint site, accessible to site members
-
Stored in the site's document library
-
Permission: Notes.ReadWrite + Sites.Read.All (Sites scope often requires admin consent)
-
Gotcha: You need the site ID, not the site URL. Resolve it first:
GET https://graph.microsoft.com/v1.0/sites/{hostname}:/{server-relative-path}
3. Group Notebooks (Microsoft 365 Groups / Teams)
GET https://graph.microsoft.com/v1.0/groups/{group-id}/onenote/notebooks
GET https://graph.microsoft.com/v1.0/groups/{group-id}/onenote/notebooks/{notebook-id}/sections
GET https://graph.microsoft.com/v1.0/groups/{group-id}/onenote/sections/{section-id}/pages
- Owned by the M365 Group (every Teams team has one)
- Stored in the group's SharePoint site document library
- Permission:
Notes.ReadWrite + Group.Read.All
- Each group has exactly one default notebook (created automatically)
Object Hierarchy
Notebook
โโโ Section Group (optional nesting)
โ โโโ Section
โ โโโ Page
โ โ โโโ Content (HTML)
โ โโโ Page
โโโ Section
โโโ Page
โ โโโ Content (HTML)
โโโ Page
Critical gotcha โ Section Groups: The API supports creating nested section groups, but the OneNote desktop and mobile apps cannot render section groups deeper than two levels. If your API creates Notebook > Group A > Group B > Group C > Section, desktop users will see a broken hierarchy. Limit nesting to one level of section groups.
Page content is HTML: Every page body is returned as XHTML. You must POST valid XHTML when creating pages (all tags self-closed, UTF-8 encoded). The Graph API silently strips invalid HTML rather than rejecting it, so malformed content appears to succeed but renders incorrectly.
API Path Construction
Build paths dynamically based on notebook location:
type NotebookLocation = "personal" | "sharepoint" | "group";
function buildOneNotePath(
location: NotebookLocation,
resourceId?: string
): string {
const base = "https://graph.microsoft.com/v1.0";
switch (location) {
case "personal":
return `${base}/me/onenote`;
case "sharepoint":
if (!resourceId) throw new Error("SharePoint requires site-id");
return `${base}/sites/${resourceId}/onenote`;
case "group":
if (!resourceId) throw new Error("Group requires group-id");
return `${base}/groups/${resourceId}/onenote`;
}
}
const path = buildOneNotePath("sharepoint", "contoso.sharepoint.com,guid1,guid2");
Service Layer Abstraction
Normalize all three locations behind a single interface so callers never deal with path differences:
import { Client } from "@microsoft/microsoft-graph-client";
import { TokenCredentialAuthenticationProvider }
from "@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials";
import { DeviceCodeCredential } from "@azure/identity";
interface NotebookTarget {
location: "personal" | "sharepoint" | "group";
resourceId?: string;
}
class OneNoteService {
private client: Client;
constructor(clientId: string, tenantId: string) {
const credential = new DeviceCodeCredential({ clientId, tenantId });
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
scopes: ["Notes.ReadWrite"],
});
this.client = Client.initWithMiddleware({ authProvider });
}
private basePath(target: NotebookTarget): string {
(target.) {
: ;
: ;
: ;
}
}
() {
..().();
}
() {
.
.()
.();
}
() {
.
.()
.()
.()
.()
.();
}
() {
.
.()
.(, )
.(htmlBody);
}
}
Decision Matrix: When to Use Which API Path
| Scenario | Path | Why |
|---|
| Personal note-taking app | /me/onenote | Simplest auth, user consent only |
| Team knowledge base | /groups/{id}/onenote | Shared with all team members automatically |
| Department wiki | /sites/{id}/onenote | SharePoint permissions control access granularly |
| Multi-user reporting tool | /users/{id}/onenote | Admin consent required; reads other users' notes |
| Cross-org integration | /sites/{id}/onenote | SharePoint external sharing supports guest access |
Multi-Tenant Architecture
For SaaS apps serving multiple M365 tenants:
- Register as multi-tenant in Azure AD (supported account types: "Accounts in any organizational directory")
- Store per-tenant metadata: each tenant needs its own site-ids, group-ids, and token cache
- Validate
tid claim in every token to prevent cross-tenant data leakage
- Discover notebooks across all three locations since different tenants organize differently:
async def discover_all_notebooks(client, site_ids: list[str], group_ids: list[str]):
"""Find notebooks across all three locations for comprehensive discovery."""
notebooks = []
personal = await client.me.onenote.notebooks.get()
for nb in (personal.value or []):
notebooks.append({"location": "personal", "name": nb.display_name, "id": nb.id})
for site_id in site_ids:
try:
site_nbs = await client.sites.by_site_id(site_id).onenote.notebooks.get()
for nb in (site_nbs.value or []):
notebooks.append({"location": "sharepoint", "resource": site_id,
"name": nb.display_name, "id": nb.id})
except Exception:
pass
for group_id in group_ids:
try:
group_nbs = await client.groups.by_group_id(group_id).onenote.notebooks.get()
for nb in (group_nbs.value or []):
notebooks.append({: , : group_id,
: nb.display_name, : nb.})
Exception:
notebooks
Output
After applying this skill, you will have: a clear mental model of the three notebook storage locations and their API paths, a reusable service abstraction that normalizes all locations into a single interface, correct permission requirements per location, and a decision matrix for choosing the right API path for your use case.
Error Handling
| Error | Cause | Fix |
|---|
404 Not Found on /sites/{id}/onenote | Wrong site-id format (must be hostname,siteGuid,webGuid) | Resolve site-id with GET /sites/{hostname}:/{path} first |
403 Forbidden on group notebooks | Missing Group.Read.All permission | Add Group.Read.All scope; may require admin consent |
403 Forbidden on SharePoint notebooks | Missing Sites.Read.All permission | Add Sites.Read.All scope; usually requires admin consent |
| Nested section groups invisible in desktop | API allows deep nesting, desktop does not | Limit section groups to one level of nesting |
400 Bad Request creating pages | Invalid XHTML in POST body | Validate HTML: close all tags, encode as UTF-8, wrap in <html><head><title>T</title></head><body>...</body></html> |
Examples
Resolve a SharePoint site ID from URL:
response = await client.sites.by_site_id(
"contoso.sharepoint.com:/sites/engineering"
).get()
site_id = response.id
List all notebooks a user can access (all locations):
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/me/onenote/notebooks?\$select=id,displayName"
curl -H "Authorization: Bearer $TOKEN" \
"https://graph.microsoft.com/v1.0/groups/GROUP_ID/onenote/notebooks?\$select=id,displayName"
Resources
Next Steps
- Apply
onenote-security-basics for permission scoping and token management
- Use
onenote-cost-tuning to optimize API call volume across multiple locations
- See
onenote-sdk-patterns for advanced query patterns with OData filters
