Support for work and school notebooks on Office 365 (in Preview)

Hi, Diane and Sharad from the OneNote team here to say "You can now access your Office 365 notebooks with the OneNote API!"

Previously, the API only supported notebooks on our consumer OneDrive service, but we've opened up access to enterprise notebooks stored on OneDrive for Business. This was a popular request from the UserVoice community, and we're happy to announce that it's in Preview starting today.

So, now you can read and write to OneNote notebooks on Office 365. Here's what you need to know:

Parity with consumer APIs

All currently supported HTTP operations for consumer notebooks have equivalent support for enterprise notebooks, with a few exceptions. For example:

  • POST ~/me/notes/pages is currently not supported. To create a page, you have to include the section ID: ~/me/notes/sections/{id}/pages. Using the ?sectionName parameter to create a page is not supported yet either. 

           NOTE:   You can now create pages in the default notebook on Office 365! So, POST ~/me/notes/pages and POST ~/me/notes/pages?sectionName are now supported.

  • $search query option is currently not supported.

Authentication and authorization

To authenticate and authorize access to enterprise notebooks, you'll use work or school account credentials with Azure AD and OAuth 2.0. You can see how to do client-side authentication in our updated Windows universal sample app. Learn more about Office 365 authentication and authorization.

Permission scopes

There's a new set of permission scopes tailored for enterprise access. For example, Notes.ReadWrite gives you full read and write access to your Office 365 notebooks, and Notes.Create lets you create Office 365 notebooks but gives limited read access.

Unlike consumer apps (which specify app permissions in the code), enterprise apps specify permissions when registering an application in Azure AD. For more information about the new scopes, see the Register your application post.

App registration

For Office 365 apps, you need to register an application on Azure AD. This means you'll need Office 365 and Azure subscriptions (trial versions are available) with administrative permissions so you can set up your Azure tenant and then register an application on Azure AD.

Service root URL

We added a user context and a notes endpoint to the service root URL to use for both Office 365 notebooks (stored in OneDrive for Business) and consumer notebooks (stored in OneDrive). For now, we only support the me context, which represents the current user. This is the new pattern:

https://www.onenote.com/api/{version}/{context}/notes/

You can use the following routes with the OneNote API, but you'll use the /beta route for Office 365 since they're currently in preview:

https://www.onenote.com/api/beta/me/notes/

https://www.onenote.com/api/v1.0/me/notes/

The target service is detected from the user's login. Once you get to a resource node (like ~/me/notes/notebooks), then the API basically works the same across platforms, and just like it works today. For example, to get the current user's notebooks, send the following GET request: https://www.onenote.com/api/beta/me/notes/notebooks

Addressable notebooks

For Office 365, you can use the OneNote API to access all notebooks in a user's OneDrive for Business.

Impact to existing apps

So, what do these changes mean for existing development against the consumer OneDrive service? Not much. We'll continue to support the same resource paths and sign-on with Live ID, so your existing apps will still work for consumer notebooks. Moving forward, we recommend you start using the new service root URL.

To make an existing OneNote app for OneDrive work with Office 365, you'll need to (1) register a separate app on Azure AD and (2) add support for Office 365 authentication. Check out the updated Windows universal sample app to see how to handle the authentication.

New shiny things

We're always working to improve your experience. For example, you can now delete pages. Support for notebooks on SharePoint sites is coming soon, as well as create section groups and create a section in a section group. Also, watch out for updated iOS and Android samples.

Thanks for your interest! If you want to see the APIs in action, check out our updated Windows universal sample app. We'd also love to hear what you think about the new Office 365 support on UserVoice.

 

Edit 9/1/2015: Added note about new support for creating pages in the default notebook with link to blog post.