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

Artikkeli
04/30/2015

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.

Jaa