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.

Comments

• Anonymous
  May 20, 2015
  This post mentions use with OneNote documents stored in OneDrive for Business.  Can the O365 API be used with OneNote's stored in O365 SharePoint?

• Anonymous
  May 22, 2015
  The comment has been removed

• Anonymous
  June 01, 2015
  Does this extend to the new WordPress OneNote plugin that your team has developed? I know our school board would be stoked to see this plugin work with our O365 accounts. It would also be great to see the OneNote Clipper working with O365 accounts.

• Anonymous
  June 16, 2015
  Hi Jared. Sorry, not yet. I passed your suggestions on to the team. You can also submit ideas to UserVoice, where others can help upvote them: onenote.uservoice.com/.../245490-onenote-api Thanks for your feedback!

• Anonymous
  July 07, 2015
  Hi, Can I use this to create OneNote notebook and assign teacher and students to it in provider hosted app of SP

• Anonymous
  August 02, 2015
  Thanks for the helpful post. Check www.office24x7.com/online.aspx for more on Online support.

• Anonymous
  November 02, 2015
  Is the support for O365 Sharepoint OneNote still on? I'm not receiving a callback with the siteId and SiteCollectionId when I make a getAsyncString call and use the fromUrl method to specify my sharepoint site. Any suggestions? thanks

• Anonymous
  December 13, 2016
  Hi, we are using business onenote in our workplace. We downloaded the genius scan application on the iPad. Some of our users can open the application with the OneNote business account and some users can not open it. What could be the reason.