OneNote permission scopes

This article describes the permission scopes that are available for the OneNote API: office.onenote, office.onenote_create, office.onenote_update, and office.onenote_update_by_app.

Last modified: January 22, 2016

Applies to: OneNote | OneNote service

Note Note

See this content on our new documentation site for consumer and enterprise OneNote APIs.

Scopes represent the permission levels that an app can request from a user in order to access the user’s OneNote resources. This article lists all of the scopes that the OneNote API makes available and explains what they allow you to do and why you would want to use them.

The scope that you choose is passed to the OneNote API when the app authenticates the user. After your users enter their Microsoft account credentials, they will see a screen or window that asks them to consent to the permissions that the app is requesting. The image below shows what the consent screen looks like when a Windows Phone app requests the office.onenote_create permission scope.

OneNote API consent window for creating pages

For platform-specific guidance and samples for passing scopes to the OneNote API and for integrating the authentication and consent prompts into your apps, see Authenticate the user for the OneNote API and the samples in the Getting started with the OneNote API section.

Your app must also request a Live Connect scope in addition to the OneNote API scope. We recommend that you request the wl.offline_access scope, which enables an app to read and update a user’s information at any time. This usually provides the best user experience, since it avoids repeated requests to sign in to the user’s Microsoft account. You should also make sure that your app requests nothing more than the minimal permissions that it will need. Users are typically more willing to consent to narrower scopes.

Be sure to look at the Live Connect Scopes and permissions article and assess which Live Connect scope will work best with your scenario.

The available scopes are designed to provide clear rules of privacy for the app and the user and also to provide enough flexibility that your app won’t need to have any more access than it needs to do its work.

Available OneNote API scopes for your app

Scope name

Description

office.onenote_create

Permission to view a list of the user’s OneNote notebooks and create new pages, but not to view or edit existing pages. Gives an app the ability to enumerate the user’s notebook hierarchy and create pages in any location.

office.onenote_update_by_app

Permission to create, view, and modify all pages created by the app.

office.onenote_update

Permission to create, view, and modify any content in the user’s OneNote notebooks and pages.

office.onenote

Permission to view OneNote notebooks and pages but not to modify them.

Show: