onenote-reference-architecture

name	onenote-reference-architecture
description	Reference architecture for OneNote integrations covering all notebook locations and API path patterns. Use when designing multi-tenant OneNote integrations or choosing between personal, SharePoint, and group notebook APIs. Trigger with "onenote architecture", "onenote api paths", "onenote sharepoint vs personal".
allowed-tools	Read, Write, Edit, Grep
version	1.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","onenote","microsoft"]
compatibility	Designed for Claude Code

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