Skip to main content
The OneNote connector reads Microsoft OneNote notebooks through Microsoft Graph and exposes their pages to the agent as a searchable catalog. A notebook’s hierarchy — notebook, section groups, sections, pages — is flattened into Notebook/Section/Page paths, so the agent can list, search, grep, and read pages the same way it works with a file source. Embedded images on a page are extracted and passed to the model when the page is read.
The OneNote connector is part of the Enterprise Edition.
OneNote is delegated-only. Microsoft retired app-only (service-principal) access to the OneNote Graph APIs on 2025-03-31 with no replacement, so — unlike SharePoint — there is no app-only path that can ever read notebooks. The admin supplies an Entra app registration; each user then signs in, and their own token is what reads pages.

​
How it works

Bag of words calls Microsoft Graph (https://graph.microsoft.com/v1.0) to walk notebooks, list pages, fetch page HTML, and pull embedded media. The agent gets note-shaped tools rather than file tools:

​
Shared catalog

Unlike OneDrive (which is per-user), the OneNote catalog is shared (catalog_ownership: shared). A OneNote deployment is usually a team knowledge base many people can see, so a per-user catalog would index the same notebook once per user and store N copies of identical page text. Instead, the first user to crawl populates the shared catalog; because a per-user crawl may only add rows (never prune), everyone else’s crawl is skipped by the incremental check when nothing has changed. This also keeps the connection eligible for scheduled reindex.

​
Indexing

By default the connector caches page text (index_mode: content). A page is a few KB of HTML and accounts hold hundreds of pages, not tens of thousands, so caching the body is affordable — and it is the only thing that makes a page findable by a word in its body, because Graph’s page-level search does not reach work or school notebooks. Set indexing to titles-only or live-only if you would rather not cache page text.

​
Notebook sources

One connection reads notebooks from a single source, chosen with Notebooks To Read: Site and group notebooks are the usual home of a shared team knowledge base and need no personal OneDrive.

​
Before you start

  • A Microsoft Entra ID app registration in your tenant, with a client secret.
  • An administrator who can grant admin consent for the Graph permissions.
  • Your Bag of words base URL, for the OAuth redirect URI.
  • For a site source: the full SharePoint site URL. For a group source: the Microsoft 365 group id.

​
Step 1 — Register an Entra ID application

1

Create the app registration

Azure Portal → Microsoft Entra ID → App registrations → New registration. Copy the Directory (tenant) ID and Application (client) ID from the Overview page.
2

Create a client secret

Certificates & secrets → New client secret. Copy the value immediately — it is shown once.
3

Add the redirect URI

Authentication → Add a platform → Web:
Replace <your-bow-host> with your Bag of words base URL.
If you already registered an app for SharePoint and OneDrive or Outlook Mail, you can reuse it — just add the OneNote permissions below and grant consent again.

​
Step 2 — Grant Microsoft Graph permissions

Under API permissions → Add a permission → Microsoft Graph → Delegated permissions, add the permissions below, then click Grant admin consent for <tenant>.
Without admin consent, sign-in fails or returns a token with no usable Graph scopes. Omit offline_access and no refresh token is issued, so users must re-authenticate whenever the access token expires.

​
Connect in Bag of words

Go to Data Sources → Add data source and choose OneNote. Enter the app registration credentials, pick a notebook source, and save. Each user then clicks Connect on the connection to sign in with their own Microsoft account before the agent can read any pages.

​
Configuration fields

Scope with include_globs to the shared notebooks a team actually uses. It keeps personal notebooks out of the org catalog and bounds indexing cost.

​
Authentication

​
Sign in with Microsoft — oauth

Scopes: system and user. OneNote has a single authentication mode. Because there is no service-principal variant, the Entra app registration is captured here rather than under a separate credential. Each user clicks Connect and completes the Microsoft authorization-code flow against this app registration. Discovery and reads then run as that user, so people see only the notebooks their own account can reach. See Authentication and access for how to require user sign-in on a connection.

​
Troubleshooting

The user has not completed Connect. OneNote is delegated-only — there is no shared credential to fall back on, so a notebook is only reachable after the user signs in.
Notes.Read (own notebooks) or Notes.Read.All (shared/site/group notebooks) was not granted or not admin-consented. Check API permissions on the app registration.
The me source needs a Microsoft 365 licence — personal (consumer) OneNote notebooks live in OneDrive and are not reachable through this API. Use a site or group source for a shared team notebook.
The app registration must have https://<your-bow-host>/api/connections/oauth/callback registered as a Web platform redirect URI, matching your Bag of words base URL exactly.
offline_access is missing from the granted delegated permissions, so no refresh token is issued.