Skip to content

Connect Microsoft OneNote

View Markdown
For agents

Give your agent this page’s Markdown link, or choose a collection.

Sponge can keep a Microsoft OneNote section in your library. The computer running Sponge signs in to Microsoft, reads your selected section, and imports its pages into sealed note records. With encrypted sync enabled, those records appear in the web library and on your other devices. The computer checks for changes while its worker is running.

Use the public Application (client) ID of a Microsoft Entra app registered for this purpose. The registration identifies the application on Microsoft’s consent screen. You can use one provided by your organization or register your own.

  1. Open Microsoft Entra admin center → App registrations → New registration and give the app a recognizable name. To support both personal and work or school OneNote, choose the account type covering any organizational directory and personal Microsoft accounts. Register an application
  2. Under Authentication, enable Allow public client flows. Copy the Application (client) ID from the registration overview. Device-code sign-in uses this public ID. Public client configuration
  3. Under API permissions, select Microsoft Graph’s delegated Notes.Read permission. The sign-in also requests offline_access so the computer can refresh while you are away. Microsoft grants the account permission to read its notebooks. The section you choose in Sponge narrows what Sponge imports. An organization may require an administrator to approve consent or permit device-code sign-in. OneNote page permissions · Microsoft device-code flow

For a single-tenant work or school registration, set SPONGE_ONENOTE_TENANT to the Directory (tenant) ID in the environment of the Sponge process that starts sign-in. The credential remembers that tenant for subsequent refreshes. The default common authority works with a registration that accepts both personal and organizational accounts.

Open Sources → Microsoft OneNote on the computer that will run the connection. Enter the client ID, then open the displayed Microsoft sign-in URL and enter the temporary code. Sign in to the account with your notebooks and accept the read permission. Sponge lists the section names alongside their notebook names so you can distinguish identically named sections. Choose a section to start the import. The command line can connect additional sections using the same local sign-in.

The command line can also start sign-in and print the available sections and credential path.

Terminal window
sponge source onenote-signin --client-id YOUR_APPLICATION_ID
sponge source onenote-sections --credential-file '/path/printed/by/signin.sqlite'
sponge source add onenote 'SECTION_ID' --credential-file '/path/printed/by/signin.sqlite' --name 'Research notebook'

Use Refresh now in Sources or sponge source refresh SOURCE_ID to check immediately. A page keeps its identity through title and content changes. A moved or removed page remains in Sponge. A refresh keeps edits and deletions made in Sponge.

Ordinary text, headings, emphasis, lists, checkboxes, simple tables and web links become Markdown. A note records its page title, creation day, modification time and the original web link when available. Free-form positioning, fonts and page layout are outside the Markdown representation. Images, ink and embedded documents appear as labeled omissions among the surrounding text, in their original positions. Pages containing only media or incomplete HTML are counted as skipped. Refresh retains an earlier copy when a page becomes unreadable, loses all its searchable text to media, or exceeds the note limit. The reader makes no attachment requests. OneNote HTML · Read page contents

A library note can contain up to 64 KiB of Markdown. Section discovery reads up to 1,000 sections. A section refresh follows Microsoft Graph’s continuation links for up to 5,000 page entries, 300 listing responses, 128 MiB of responses and ten minutes of work. Large notebooks can be connected one section at a time.

The access and refresh tokens live in a private, device-local SQLite file under your library’s runtime/onenote directory. Only that device’s user can read the file. Keep private copies of that directory protected like other sign-in credentials. A connection stores its section ID and the path to that file on the same computer.

Disconnect stops that section’s refreshes and retains its records. Other sections using the same sign-in can continue. To end the Microsoft grant, revoke the app’s permission in your Microsoft account or your organization’s application portal. You can remove its local sign-in file after disconnecting every section that uses it. If Microsoft revokes or expires the sign-in, sign in again and reconnect the same section using the new credential file. Microsoft refresh tokens

Documentation drafted with AI and checked against the product source.