OneNote Deploy Integration

Overview

Deploying OneNote integrations into containers breaks local development assumptions: MSAL token caches vanish on restart, health checks must validate Graph API connectivity (not just HTTP 200), and graceful shutdown must flush token state. This skill provides production-ready Dockerfile, Docker Compose, and Kubernetes manifests with MSAL token persistence, health/readiness probes that verify actual Graph reachability, and SIGTERM handling.

Prerequisites

• Docker 24+ and Docker Compose v2
• Node.js 20 LTS or Python 3.11+
• Azure AD app registration with delegated permissions (Notes.Read, Notes.ReadWrite)
• Redis (recommended for multi-replica) or persistent volume for token cache

Instructions

Dockerfile

FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY tsconfig.json src/ ./
RUN npm run build

FROM node:20-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
RUN mkdir -p /app/.cache/msal && chown -R node:node /app/.cache
USER node
ENV NODE_ENV=production MSAL_CACHE_DIR=/app/.cache/msal
HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
  CMD curl -sf http://localhost:3000/health || exit 1
EXPOSE 3000
CMD ["node", "dist/index.js"]

MSAL Token Cache Persistence

File-based (single replica):

// src/auth/token-cache.ts
import { readFile, writeFile, mkdir } from "fs/promises";
import { existsSync } from "fs";
import path from "path";

const CACHE_DIR = process.env.MSAL_CACHE_DIR || "/app/.cache/msal";
const CACHE_FILE = path.join(CACHE_DIR, "token-cache.json");

export async function loadCache(): Promise<string | null> {
  try {
    if (existsSync(CACHE_FILE)) return await readFile(CACHE_FILE, "utf-8");
  } catch (err) { console.error("Failed to load token cache:", err); }
  return null;
}

export async function saveCache(contents: string): Promise<void> {
  await mkdir(CACHE_DIR, { recursive: true });
  await writeFile(CACHE_FILE, contents, { mode: 0o600 });
}

Redis-based (multi-replica):

// src/auth/redis-cache.ts
import { createClient, RedisClientType } from "redis";
const CACHE_KEY = "msal:onenote:token-cache";
let redis: RedisClientType;

export async function initRedisCache(): Promise<void> {
  redis = createClient({ url: process.env.REDIS_URL || "redis://localhost:6379" });
  redis.on("error", (err

OneNote Hello World

Overview

Create your first OneNote notebook, section, and page through the Graph API. The critical pitfall this skill addresses: OneNote pages require strict XHTML (not regular HTML). Missing closing tags, unsupported attributes, or table features like rowspan/colspan cause silent content corruption where the API returns 200 OK but the page renders incorrectly or with missing content.

This skill walks through the full creation chain — notebook, section, page — with correct XHTML, then reads back the content to demonstrate that output HTML differs from input HTML.

Prerequisites

• Completed onenote-install-auth — you have a working GraphServiceClient (Python) or Client (TypeScript)
• Azure AD app with Notes.ReadWrite permission scope
• Node.js 18+ or Python 3.10+

Instructions

Step 1: Create a Notebook

// TypeScript — create a new notebook
const notebook = await client.api("/me/onenote/notebooks").post({
  displayName: "Dev Integration Test"
});
console.log(`Notebook created: ${notebook.displayName} (${notebook.id})`);
// Save notebook.id — you need it for creating sections

# Python — create a new notebook
from msgraph.generated.models.notebook import Notebook

request_body = Notebook(display_name="Dev Integration Test")
notebook = await client.me.onenote.notebooks.post(request_body)
print(f"Notebook created: {notebook.display_name} ({notebook.id})")

Naming rules: Notebook names must be unique per user. If a notebook with the same name exists, you get a 400 error with code 20117. Use a timestamp suffix for test notebooks: f"Test-{datetime.now().isoformat()}".

Step 2: Create a Section

// TypeScript — create a section inside the notebook
const section = await client
  .api(`/me/onenote/notebooks/${notebook.id}/sections`)
  .post({ displayName: "Getting Started" });
console.log(`Section created: ${section.displayName} (${section.id})`);

# Python — create a section
from msgraph.generated.models.onenote_section import OnenoteSection

section_body = OnenoteSection(display_name="Getting Started")
section = await client.me.onenote.notebooks.by_notebook_id(
    notebook.id
).sections.post(section_body)
print(f"Section created: {section.display_name} ({section.id})")

Step 3: Create a Page with Correct XHTML

This is where most integrations break. OneNote requires XHTML — every tag must close, the document must be UTF-8, and several HTML features are silently dropped.

VALID XHTML (this works):

<

OneNote Install & Auth

Overview

Set up Microsoft Graph API authentication for OneNote using delegated credentials via MSAL. This skill walks through Azure AD app registration, SDK installation, permission scope selection, token caching, and connection verification for both Python and TypeScript.

BREAKING CHANGE (March 31, 2025): App-only authentication (ClientSecretCredential) was deprecated for OneNote APIs. All integrations MUST use delegated auth — DeviceCodeCredential or InteractiveBrowserCredential. If your existing code uses ClientSecretCredential with OneNote endpoints, it will receive 403 Forbidden on every call. This skill provides the correct migration path.

Prerequisites

• Azure account with permission to register applications (Azure AD admin or Application Developer role)
• Node.js 18+ or Python 3.10+
• Access to Azure Portal App Registrations
• A OneNote account (personal Microsoft account or Microsoft 365 work/school account)

Instructions

Step 1: Register an Azure AD Application

1. Navigate to Azure Portal > App Registrations
2. Click New registration
3. Set the Name (e.g., onenote-integration-dev)
4. Under Supported account types, choose:

• Single tenant — only your organization (most restrictive, recommended for internal tools)
• Multi-tenant — any Azure AD directory (needed if serving multiple orgs)
• Multi-tenant + personal — includes personal Microsoft accounts (needed if targeting consumer OneNote)

1. Under Redirect URI, select Public client/native and set URI to http://localhost
2. Click Register and note the Application (client) ID and Directory (tenant) ID

Step 2: Configure API Permissions

1. In your app registration, go to API permissions > Add a permission > Microsoft Graph > Delegated permissions
2. Add the appropriate scope:

1. Click Grant admin consent if you h

OneNote — Performance Tuning & Optimization

Overview

OneNote performance degrades predictably at scale: notebooks with 100+ sections take 3-5 seconds per API call when using $expand, pages with embedded images over 4MB fail silently, and sections hitting the page limit return 507 Insufficient Storage. Image uploads are capped at 25MB per multipart part, and requesting full page content for hundreds of pages without $select can exhaust your rate budget in seconds.

This skill provides tested patterns for every performance bottleneck: selective $expand and $select for minimal payloads, image compression before upload, batch requests via $batch, pagination with $top to avoid loading thousands of pages, and caching strategies that invalidate on change detection.

Key pain points addressed:

• Full $expand=sections($expand=pages) on large notebooks can take 10+ seconds and return multi-MB responses
• Image uploads silently fail when a single multipart part exceeds 25MB — no error, just missing image
• 507 Insufficient Storage when a section hits its page limit (approximately 5,000 pages)
• Page content retrieval (GET /pages/{id}/content) is 5-10x slower than metadata-only requests

Prerequisites

• Azure app registration with delegated permissions: Notes.ReadWrite
• App-only auth deprecated March 31, 2025 — use delegated auth only
• Python: pip install msgraph-sdk azure-identity Pillow (Pillow for image compression)
• Node/TypeScript: npm install @microsoft/microsoft-graph-client @azure/identity @azure/msal-node sharp (sharp for image compression)

Instructions

Step 1 — Use $select to Minimize Payload Size

Every Graph API call should specify $select to return only the fields you need. The default response includes navigation properties, OData metadata, and verbose timestamps that inflate payloads:

// BAD — returns ~2KB per page with all metadata
const pages = await client.api("/me/onenote/pages").get();

// GOOD — returns ~200 bytes per page with only needed fields
const pages = await client.api("/me/onenote/pages")
  .select("id,title,lastModifiedDateTime")
  .get();

// For notebooks, avoid expanding everything
// BAD — can take 10+ seconds on large notebooks
const notebooks = await client.api("/me/onenote/notebooks")
  .expand("sections($expand=pages)")
  .get();

// GOOD — get structure first, then drill into sections on demand
const notebooks = await client.api("/me/onenote/notebooks")
  .select("id,displayName,lastModifiedDateTime,sectionsUrl")
  .get();

Payload size comparison for a notebook with 50 sect

OneNote — Rate Limit Handling & Request Throttling

Overview

Microsoft Graph rate limits OneNote at 600 requests per 60 seconds per user and 10,000 requests per 10 minutes per app/tenant. When you exceed either limit, the API returns 429 Too Many Requests with a Retry-After header specifying how many seconds to wait. Most implementations either ignore this header entirely (retrying immediately, making things worse) or use a fixed backoff that wastes capacity.

This skill implements a token bucket rate limiter, queue-based request throttling, and proper Retry-After header parsing. For multi-user apps, it tracks per-user and per-tenant budgets independently.

Key pain points addressed:

• The Retry-After header value is in seconds (not milliseconds) — many implementations parse this wrong
• The per-user limit (600/60s) is separate from the per-tenant limit (10,000/10min) — you can hit one without the other
• Batch requests ($batch) count as one request toward the limit, regardless of how many operations are inside
• After a 429, subsequent requests to ANY OneNote endpoint are throttled — not just the endpoint that triggered it

Prerequisites

• Azure app registration with delegated permissions: Notes.ReadWrite
• App-only auth deprecated March 31, 2025 — use delegated auth only
• Python: pip install msgraph-sdk azure-identity
• Node/TypeScript: npm install @microsoft/microsoft-graph-client @azure/identity @azure/msal-node
• Optional: npm install p-queue for production queue management

Instructions

Step 1 — Understand the Rate Limit Structure

When either limit is hit:

• Response status: 429 Too Many Requests
• Response header: Retry-After: (integer, not milliseconds)
• All subsequent OneNote requests for that scope are blocked until the window resets
• Non-OneNote Graph endpoints (Outlook, OneDrive) are not affected

Step 2 — Token Bucket Rate Limiter (TypeScript)

A token bucket preemptively throttles requests to stay below the limit, avoiding 429s entirely:

class TokenBucket {
  private tokens: number;
  private lastRefill: number;
  private readonly maxTokens: number;
  private readonly refillRate: number; // tokens per millisecond

  constructor(

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)
• Can

OneNote Security Basics

Overview

OneNote Graph API security changed fundamentally on March 31, 2025, when Microsoft deprecated app-only authentication for OneNote endpoints. Every integration must now use delegated authentication through MSAL, which means real users must sign in — no more background service accounts with client secrets. This skill covers the full security surface: permission scoping, token lifecycle management, MSAL cache serialization, credential storage, and multi-tenant hardening. Get any of these wrong and your integration either breaks silently (expired tokens returning 401s) or over-provisions access (Notes.ReadWrite.All when Notes.Read suffices).

Prerequisites

• Azure AD app registration with redirect URI configured at https://portal.azure.com/#blade/MicrosoftAADRegisteredApps
• Microsoft 365 license (E3/E5/Business) with OneNote enabled
• Python: pip install msgraph-sdk azure-identity msal or Node: npm install @microsoft/microsoft-graph-client @azure/identity @azure/msal-node
• Understanding of OAuth 2.0 authorization code flow and delegated permissions

Instructions

Permission Scope Matrix

Choose the minimum scope required for your use case:

Least-privilege recommendations:

• Read-only dashboards: Notes.Read (user consent only)
• Personal note creation: Notes.ReadWrite (user consent only)
• Cross-user/organizational access: Notes.ReadWrite.All (requires tenant admin approval)
• Write-only ingestion: Notes.Create (cannot read back what was written)

Delegated Authentication Setup (Post-2025 Mandatory)

CRITICAL: App-only authentication (ClientSecretCredential) was deprecated for OneNote endpoints on March 31, 2025. All code below uses delegated auth exclusively.

Python — Device Code Flow (headless/CLI environments):

from azure.identity import DeviceCodeCredential
from msgraph import GraphServiceClient
import os

CLIENT_ID = os.environ["AZURE_CLIENT_ID"]
TENANT_ID = os.environ["AZURE_TENANT_ID"]

# Minimal scopes — only request what you ne

OneNote Upgrade & Migration

Overview

Microsoft shipped three breaking changes to OneNote integrations in under two years: webhook decommissioning (June 2023), search endpoint deprecation (April 2024), and app-only auth deprecation (March 2025). The Graph SDK itself had breaking changes between v5 and v6. This skill provides exact migration diffs, verification steps, and rollback strategies for each breaking change.

Prerequisites

• Existing OneNote integration using Graph API
• Node.js 18+ (TypeScript SDK) or Python 3.10+ (Python SDK)
• Git for branch-based migration with rollback capability
• Azure portal access for app registration changes (auth migration)

Instructions

Breaking Changes Timeline

Migration 1: App-Only to Delegated Auth

Before (broken after March 2025):

// OLD — ClientSecretCredential (DEPRECATED for OneNote)
import { ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(TENANT_ID, CLIENT_ID, CLIENT_SECRET);
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ["https://graph.microsoft.com/.default"],
});

After:

// NEW — DeviceCodeCredential (required)
import { DeviceCodeCredential } from "@azure/identity";
const credential = new DeviceCodeCredential({
  clientId: CLIENT_ID, tenantId: TENANT_ID,
  userPromptCallback: (info) =>
    console.log(`Open ${info.verificationUri} and enter code: ${info.userCode}`),
});
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ["Notes.Read", "Notes.ReadWrite"],  // Explicit, not .default
});
const client = Client.initWithMiddleware({ authProvider });

Python equivalent:

# OLD: credential = ClientSecretCredential(tenant_id, client_id, client_secret)
# NEW:
from azure.identity import DeviceCodeCredential
credential = DeviceCodeCredential(client_id=CLIENT_ID, tenant_id=TENANT_ID)

Required Azure portal changes: Add "Mobile and desktop applications" platform with http://localhost redirect URI to your app registration.

Migration 2: Webhooks to Polling

// OLD — Webhook subscription (DECOMMISSIONED June 2023)
// 

OneNote — Change Detection (Polling & Delta Queries)

Overview

> OneNote webhooks were decommissioned June 16, 2023. The Graph subscription API (POST /subscriptions with changeType: "updated" on OneNote resources) returns 400 Bad Request. Unlike Outlook mail, calendar, and OneDrive — which still support push notifications — OneNote has no webhook replacement. You must poll.

This skill implements efficient change detection for OneNote using lastModifiedDateTime comparisons, delta query patterns, and rate-limit-aware polling intervals. The approach balances freshness (detecting changes within minutes) against the 600 requests/minute per-user rate limit.

Key pain points addressed:

• Subscription API for OneNote resources returns 400 — do not attempt it
• Delta queries (/me/onenote/pages/delta) are not officially documented but work on some tenants
• Polling must stay within rate budget (600/min per user, 10,000/10min per tenant)
• Change detection requires comparing timestamps, not content diffs (output HTML is unstable)

Prerequisites

• Azure app registration with delegated permissions: Notes.Read or Notes.ReadWrite
• App-only auth deprecated March 31, 2025 — use delegated auth only
• Python: pip install msgraph-sdk azure-identity
• Node/TypeScript: npm install @microsoft/microsoft-graph-client @azure/identity @azure/msal-node
• A persistent store for tracking last-seen timestamps (Redis, SQLite, file system)

Instructions

Step 1 — Understand Why Webhooks Do Not Work

// DO NOT DO THIS — it will return 400 Bad Request
// OneNote webhooks decommissioned June 16, 2023
const subscription = await client.api("/subscriptions").post({
  changeType: "updated",
  notificationUrl: "https://yourapp.com/webhooks/onenote",
  resource: "/me/onenote/pages",  // NOT SUPPORTED
  expirationDateTime: new Date(Date.now() + 3600000).toISOString(),
});
// Error: "Subscription validation request failed. Resource not found."

For comparison, these Graph resources still support webhooks: Outlook messages, calendar events, OneDrive files, Teams messages, Planner tasks. OneNote is the notable exception.

Step 2 — Implement Timestamp-Based Polling (TypeScript)

The core pattern: periodically list pages ordered by lastModifiedDateTime and compare against your stored watermark.

import { Client } from "@microsoft/microsoft-graph-client";

interface ChangeEvent {
  pageId: string;
  title: string;
  sectionId: string;
  modifiedAt: string;
  changeType: "created" | "modified";
}

class OneNotePolle