Manage permissions on OneNote entities

  • Article

Applies to: Enterprise notebooks on Office 365

You can use the permissions endpoint to manage read or write permissions to notebooks, section groups, and sections.

POST ../permissions

GET ../permissions

GET ../permissions/{permission-id}

DELETE ../permissions/{permission-id}

Note

Managing permissions is supported for Office 365 personal, site, and unified group notebooks, but not for consumer notebooks on OneDrive.

Construct the request URI

  1. To construct the request URI, start with the service root URL for your platform:

    Notebooks on OneDrive for Business

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

    https://www.onenote.com/api/v1.0/users/{id}/notes/

    SharePoint site notebooks

    https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

    Unified group notebooks

    https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/

  2. Append the path to the target notebook, section group, or section entity, followed by the permissions or permissions/{id} endpoint.

Your full request URI will look something like these examples:

https://www.onenote.com/api/v1.0/me/notes/notebooks/{id}/permissions/{id}

https://www.onenote.com/api/v1.0/users/{id}/notes/sectiongroups/{id}/permissions

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/notebooks/{id}/permissions

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/sections/{id}/permissions/{id}

Note

Learn more about the service root URL.

Create or update permissions

To create or update permissions for a notebook, section group, or section, send a POST request to the appropriate endpoint. You can create or update only one permission per request.

Permissions are applied to all OneNote entities down the inheritance chain.

You can update permissions to grant more permissive access. But to restrict access, you must delete the existing permission and create a new permission. See Permission inheritance and precedence.

Create or update permissions for a notebook

POST ../notebooks/{notebook-id}/permissions

Create or update permissions for a section group

POST ../sectiongroups/{sectiongroup-id}/permissions

Create or update permissions for a section

POST ../sections/{section-id}/permissions

In the message body, send a JSON object with the required parameters.

{
    "userRole": "user-role", 
    "userId": "user-login-id"
}
Parameter Description
userRole The type of permission: Owner, Contributor, or Reader.
userId The login of the user or group to assign the permission to. The API accepts the claims format which includes the membership provider name (i:0#.f|membership|username@domainname.com), or the user principal login name only (username@domainname.com).

Example

The following request creates a permission for the specified notebook.

Request

POST ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "userRole": "Owner", 
    "userId": "i:0#.f|membership|alexd@domainname.com"
}

Response

HTTP/1.1 201 Created

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions/$entity",
  "userRole":"Owner",
  "userId":"i:0#.f|membership|alexd@domainname.com",
  "name":"Alex Darrow",
  "id":"1-23",
  "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
}

Request and response information

The following information applies to POST /permissions requests.

Request data Description
Protocol All requests use the SSL/TLS HTTPS protocol.
Authorization header

Bearer {token}, where {token} is a valid OAuth 2.0 access token for your registered app.

If missing or invalid, the request fails with a 401 status code. See Authenticate using Azure AD (enterprise apps).
Permission scope Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All


Response data Description
Success code A 201 HTTP status code.
Response body An OData representation of the permission in JSON format. See Get permissions for a description of a Permission object.
Errors If the request fails, the API returns errors in the response body.
X-CorrelationId header A GUID that uniquely identifies the request. You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues.

Get permissions

To get permissions for a notebook, section group, or section, send a GET request to the appropriate endpoint.

Get permissions for a notebook

GET ../notebooks/{notebook-id}/permissions

Get a specific permission for a notebook

GET ../notebooks/{notebook-id}/permissions/{permission-id}

Get permissions for a section group

GET ../sectiongroups/{sectiongroup-id}/permissions

Get a specific permission for a section group

GET ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

Get permissions for a section

GET ../sections/{section-id}/permissions

Get a specific permission for a section

GET ../sections/{section-id}/permissions/{permission-id}


GET requests return the highest permission for a user role on the target entity. For more information, see Permission inheritance and precedence.

GET /permissions requests support OData query options, as follows:

GET ../permissions[?filter,orderby,select,top,skip,count]

GET ../permissions/{permission-id}[?select]

Note

The permissions endpoint does not support the expand query option.

To learn more about getting OneNote entities, including supported query string options and examples, see Get OneNote content and structure.

Permission object

A permission contains the following properties.

Property Description
name The display name of the user or group principal. Example: "name":"Everyone"
id The unique identifier of the permission, in the form 1-{principal-member-id}. Example: "id":"1-4"
self The URL of the permission object.
userId The login of the user or group the permission is assigned to. This value is always returned in the claims format, for example: i:0#.f|membership|username@domainname.com.
userRole The type of permission: Owner, Contributor, or Reader.

Example

The following request gets all permissions for the specified notebook.

Request

GET ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Accept: application/json

Response

HTTP/1.1 200

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions",
  "value":[
  {
    "userRole":"Owner",
    "userId":"c:0(.s|true",
    "name":"Everyone",
    "id":"1-4",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/1-4"
  },
  {
    "userRole":"Owner",
    "userId":"c:0-.f|rolemanager|spo-grid-all-users/8461cbdd-15a6-45c8-b177-ac24f48a8bee",
    "name":"Everyone except external users",
    "id":"1-5",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-5"
  },
  {
    "userRole":"Owner",
    "userId":"i:0#.f|membership|alexd@domainname.com",
    "name":"Alex Darrow",
    "id":"1-23",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
  }]
}

Request and response information

The following information applies to GET /permissions requests.

Request data Description
Protocol All requests use the SSL/TLS HTTPS protocol.
Authorization header

Bearer {token}, where {token} is a valid OAuth 2.0 access token for your registered app.

If missing or invalid, the request fails with a 401 status code. See Authenticate using Azure AD (enterprise apps).
Permission scope Notes.Read, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All


Response data Description
Success code A 200 HTTP status code and the requested permissions.
Response body An OData representation of the permissions in JSON format.
Errors If the request fails, the API returns errors in the response body.
X-CorrelationId header A GUID that uniquely identifies the request. You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues.

Delete permissions

To delete a permission for a notebook, section group, or section, send a DELETE request to the appropriate endpoint. You can delete one permission per request.

When you delete a permission, it is deleted from all the OneNote entities down the inheritance chain.

Delete a permission for a notebook

DELETE ../notebooks/{notebook-id}/permissions/{permission-id}

Delete a permission for a section group

DELETE ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

Delete a permission for a section

DELETE ../sections/{section-id}/permissions/{permission-id}

Example

The following request deletes a permission for the specified notebook.

DELETE ../v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23
Authorization: Bearer {token}
Accept: application/json

Request and response information

The following information applies to DELETE /permissions requests.

Request data Description
Protocol All requests use the SSL/TLS HTTPS protocol.
Authorization header

Bearer {token}, where {token} is a valid OAuth 2.0 access token for your registered app.

If missing or invalid, the request fails with a 401 status code. See Authenticate using Azure AD (enterprise apps).
Permission scope Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, or Notes.ReadWrite.All


Response data Description
Success code A 204 HTTP status code.
Errors If the request fails, the API returns errors in the response body.
X-CorrelationId header A GUID that uniquely identifies the request. You can use this value along with the value of the Date header when working with Microsoft support to troubleshoot issues.

Permissions, inheritance, and precedence

You can set the following permissions on notebooks, section groups, and sections.

Permission Description
Reader Read-only access to notebooks, section groups, and sections.
Contributor Can add, edit, and delete notebooks, section groups, and sections.
Owner All the permissions above, also can manage permissions (get, create, and delete).

When managing permissions on OneNote entities, you should understand permission inheritance and precedence.

  • Inheritance. Entities inherit the permissions of their parent. So, notebooks inherit the permissions of the document library that contains the notebook. And in turn, these permissions are inherited by the child section groups and sections within the notebook. When you set explicit permissions on a notebook, section group, or section, the permissions also propagate to its child objects.

  • Precedence. When conflicting permissions are set on a OneNote entity, the highest (most permissive) permission is honored. Users and groups might be granted conflicting levels of access when multiple permissions are applied to an entity (either explicitly or inherited), or when the user or group belongs to multiple roles.

These principles determine how the OneNote API manages permissions. For example:

  • When you create a permission for a notebook or section group, the permission is pushed down to all children.

  • When you delete a permission for a notebook or section group, the permission is deleted from all children.

  • When you get permissions, the OneNote API returns only the highest permission for roles that have conflicting permissions.

  • You can update permissions to grant more permissive access to a user or group. But if you want to restrict access, you must first delete the more permissive permission and then create a new permission with the restrictive access.

    This is because a POST /permissions request actually appends a user role to the permissions collection for the entity, and the most permissive access is honored. So in other words, you can update a Reader permission to have Contributor or Owner access, but you can't update a Contributor permission to allow only Reader access.

Construct the OneNote service root URL

The OneNote service root URL uses the following format for all calls to the OneNote API.

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

The version segment in the URL represents the version of the OneNote API that you want to use.

  • Use v1.0 for stable production code.

  • Use beta to try out a feature that's in development. Features and functionality in beta may change, so you shouldn't use it in your production code.

The location segment in the URL represents the location of the notebooks that you want to access:

  • Notebooks on OneDrive for Business

    • Use me for OneNote content that’s owned by the current user.

    • Use users/{id} for OneNote content that the specified user (in the URL) has shared with the current user. Use the Azure AD Graph API to get user IDs.

  • SharePoint site notebooks

    • Team sites and other SharePoint sites can contain OneNote notebooks in their document libraries.

    • Use myOrganization/siteCollections/{id}/sites/{id} for OneNote content in a site in the tenant that the current user is logged into. Only the current tenant is supported, accessed using the myOrganization keyword. Learn how to get site IDs.

  • Unified group notebooks

    • Unified groups (also called Office 365 groups) are part of the Office 365 connected experience. Group members can share notebooks, files, and email.

    • Use myOrganization/groups/{id} for OneNote content in the specified group that the current user is a member of. Unified groups are the only supported group type. Use the Azure AD Graph API to get group IDs.

Use the FromUrl method to get the site collection and site IDs

You can use the FromUrl method to get the site collection and site IDs for a specified absolute site URL. You should make this call only when needed, and then store the values for future use.

The format of the site URL depends on your configuration, for example https://domain.sharepoint.com/site-a or https://domain.com/sites/site-a.

Example request

GET https://www.onenote.com/api/v1.0/myOrganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')

Authorization: Bearer {token}

Accept: application/json

Example response

{"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.SiteMetadata", "siteCollectionId":"09d1a587-a84b-4264-3d15-669429be8cc5", "siteId":"d9e4d5c8-683f-4363-89ae-18c4e3da91e9"}

Requirements for using FromUrl and working with SharePoint site notebooks:

  • You can only create OneNote notebooks, section groups, sections, and pages on sites that have a default document library. (Some site templates don't create a default document library.) However, GET requests return OneNote content from all document libraries on the site.

  • The OneNote service root URL is immutable, meaning you can't use a SharePoint REST API site path and then tack the notes endpoint onto it.

  • The user on whose behalf you're calling must be a member of the site.

  • FromUrl works only with sites that have been indexed. It may take several hours to index a new site.

See also