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

/pages?search=

ClientSecretCredential

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

Migration 2: Webhooks to Polling

// OLD — Webhook subscription (DECOMMISSIONED June 2023)
// await client.api("/subscriptions").post({ resource: "/me/onenote/pages", ... });

// NEW — Polling with delta link tracking
async function pollForChanges(client: any, deltaLink: string | null) {
  const endpoint = deltaLink || "/me/onenote/notebooks";
  const response = await client.api(endpoint)
    .header("Prefer", "odata.track-changes").get();

  for (const item of response.value || []) {
    await processChange(item);
  }
  return response["@odata.deltaLink"] || deltaLink;
}

// Poll every 60s (stays under 600 req/60s per-user rate limit)
let deltaLink: string | null = null;
setInterval(async () => {
  try { deltaLink = await pollForChanges(client, deltaLink); }
  catch (err: any) {
    if (err?.statusCode === 429) {
      console.warn(`Rate limited. Retry after ${err.headers?.["retry-after"] ?? 30}s`);
    }
  }
}, 60_000);

Migration 3: Search Endpoint to OData Filters

// OLD — Search endpoint (DEPRECATED April 2024)
// const results = await client.api("/me/onenote/pages").query({ search: "term" }).get();

// NEW — OData filter for title, client-side for content
async function searchPages(client: any, query: string) {
  // Server-side title filter
  const titleMatches = await client.api("/me/onenote/pages")
    .filter(`contains(title,'${query.replace(/'/g, "''")}')`)
    .top(50).orderby("lastModifiedDateTime desc").get();

  // Client-side content search (Graph no longer supports full-text)
  const contentMatches: any[] = [];
  const pages = await client.api("/me/onenote/pages").top(100)
    .orderby("lastModifiedDateTime desc").get();
  for (const page of pages.value) {
    const html = await client.api(`/me/onenote/pages/${page.id}/content`).get();
    if (html.replace(/<[^>]+>/g, "").toLowerCase().includes(query.toLowerCase())) {
      contentMatches.push(page);
    }
  }

  // Deduplicate
  const seen = new Set(titleMatches.value.map((p: any) => p.id));
  return [...titleMatches.value, ...contentMatches.filter((m) => !seen.has(m.id))];
}

Migration 4: Graph SDK v5 to v6 (TypeScript)

// SDK v5 — callback-based auth (REMOVED in v6)
const client = Client.init({
  authProvider: (done) => done(null, accessToken),
});

// SDK v6 — middleware-based auth (REQUIRED)
import { TokenCredentialAuthenticationProvider } from
  "@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials";
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ["Notes.Read", "Notes.ReadWrite"],
});
const client = Client.initWithMiddleware({ authProvider });

Migration Checklists

Auth migration: Remove

AZURE_CLIENT_SECRET

.default

GET /me/onenote/notebooks

SDK upgrade: Update

@microsoft/microsoft-graph-client

Client.init()

Client.initWithMiddleware()

Search migration: Replace

/pages?search=

$filter

Feature Detection at Runtime

export function requiresDelegatedAuth(): boolean { return true; } // Since March 2025
export function isSearchEndpointAvailable(): boolean { return false; } // Since April 2024
export function isWebhookAvailable(): boolean { return false; } // Since June 2023

Rollback Strategy

Use a feature flag for gradual auth migration:

const useDelegated = process.env.ONENOTE_AUTH_MODE !== "legacy";
const credential = useDelegated
  ? new DeviceCodeCredential({ clientId, tenantId })
  : new ClientSecretCredential(tenantId, clientId, clientSecret); // Legacy fallback

Output

• Auth migration:

  ClientSecretCredential

  to

  DeviceCodeCredential

  with code diff
• Webhook migration: subscription API to polling with delta queries
• Search migration: deprecated endpoint to OData filters + client-side search
• SDK v5 to v6:

  Client.init()

  to

  Client.initWithMiddleware()

• Migration checklists and feature detection module
• Rollback strategy with feature flag pattern

Error Handling

403 Forbidden

http://localhost

InvalidScope

.default

Notes.Read

Notes.ReadWrite

TypeError: Client.init is not a function

Client.init

Client.initWithMiddleware

404

$filter

400

Examples

# Check which migrations your codebase needs
grep -r "ClientSecretCredential" src/ --include="*.ts" --include="*.py"
grep -r "search=" src/ --include="*.ts" --include="*.py"
grep -r "/subscriptions" src/ --include="*.ts" --include="*.py"
grep -r "Client.init(" src/ --include="*.ts"

// Smoke test after auth migration
const client = getGraphClient();
const nb = await client.api("/me/onenote/notebooks").top(1).get();
console.log("Auth migration OK:", nb.value.length, "notebooks");

Resources

• OneNote API Overview
• Graph API Known Issues
• Azure App Registration
• MSAL Python
• OneNote Error Codes

Next Steps

• Set up CI for migrated code with

  onenote-ci-integration

• Debug migration issues with

  onenote-debug-bundle

• Review security after migration with

  onenote-security-basics