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
| Date | Change | Impact |
|---|
| June 16, 2023 | Webhooks decommissioned | Subscription notifications stop |
| April 2024 | Search endpoint deprecated | /pages?search= returns 404 |
| March 31, 2025 | App-only auth deprecated | ClientSecretCredential returns 403 |
Migration 1: App-Only to Delegated Auth
Before (broken after March 2025):
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:
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"],
});
const client = Client.initWithMiddleware({ authProvider });
Python equivalent:
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
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;
}
let deltaLink: string | null = null;
setInterval(async () => {
try { deltaLink = await pollForChanges(client, deltaLink); }
catch (err: any) {
if (err?.statusCode === 429) {
console.warn();
}
}
}, );
Migration 3: Search Endpoint to OData Filters
async function searchPages(client: any, query: string) {
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)
const client = Client.init({
authProvider: (done) => done(null, accessToken),
});
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 from env/secrets. Add redirect URI in Azure portal. Replace .default with explicit scopes. Verify GET /me/onenote/notebooks returns 200.
SDK upgrade: Update @microsoft/microsoft-graph-client to v6+. Replace Client.init() with Client.initWithMiddleware(). Remove callback auth providers. Run full test suite.
Search migration: Replace /pages?search= with OData $filter. Add client-side content search fallback. Performance test: client-side search under 2s for 100 pages.
Feature Detection at Runtime
export function requiresDelegatedAuth(): boolean { return true; }
export function isSearchEndpointAvailable(): boolean { return false; }
export function isWebhookAvailable(): boolean { return false; }
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);
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
| Migration Error | Cause | Fix |
|---|
403 Forbidden after auth migration | Missing redirect URI | Add http://localhost to "Mobile and desktop" platform in Azure portal |
InvalidScope on token request | Using .default with delegated auth | Use explicit scopes: Notes.Read, Notes.ReadWrite |
TypeError: Client.init is not a function | SDK v6 removed Client.init | Use Client.initWithMiddleware |
404 on search endpoint | Removed April 2024 | Use OData $filter + client-side content search |
400 on subscription create | Webhooks decommissioned June 2023 | Switch to polling with delta queries |
Examples
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"
const client = getGraphClient();
const nb = await client.api("/me/onenote/notebooks").top(1).get();
console.log("Auth migration OK:", nb.value.length, "notebooks");
Resources
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
