Create sharing links on OneNote entities

  • Article

Applies to: Enterprise notebooks on Office 365

Create a sharing link to share a OneNote file with anyone. You can use this API is to create, get, and revoke anonymous guest links. The guest links will grant editing permissions or view-only permissions without requiring a log-in.

GET ../sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetAnonymousSharingLink

POST ../sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

DELETE ../sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.RevokeAnonymousSharingLink

Note

Sharing links are supported for Office 365 personal, site, and group notebooks, but not for consumer notebooks on OneDrive. At this time, only sectiongroup entities are currently supported.

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. Add the path to the section group entity, followed by the Sharing Link Functions.

Your full request URI will look something like these examples:

https://www.onenote.com/api/v1.0/me/notes/sectiongroups/{id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

https://www.onenote.com/api/v1.0/users/{id}/notes/sectiongroups/{id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/sectiongroups/{id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/sections/{id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

To create an anonymous link for a section group, send a GET request using the appropriate endpoint.

GET ../sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetAnonymousSharingLink

The function parameter accessLevel enum indicates the access level of the sharing link.

Parameter accessLevel enum values Access level of sharing link to create (view or edit)
View Creates a read-only link to the item.
Edit Creates a read-write link to the item.

Example

Request

GET ../api/v1.0/me/notes/sectionGroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetAnonymousSharingLink(accessLevel=Microsoft.OneNote.Api.SharingLinkAccessLevel'View') 
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

Response

HTTP/1.1 200 Ok

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Edm.String",
  "value":"https://www.contoso.com/_layouts/15/WopiFrame.aspx?folderid=084a6fcc95ab54a678257e1b9cba41e7e&authkey=AXXriBu-O475sT4tfJeJDkA&FixProgId=1"
}

Request and response information

The following information applies to GET /GetAnonymousSharingLink 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, or Notes.ReadWrite.All


Response data Description
Success code A 200 HTTP status code.
Response body An OData representation of the value 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.

Follow these steps to get the existing link or create one if one does not exist. The anonymous link can be used to view a OneNote file without logging in.

POST ../api/v1.0/me/notes/sectionGroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink

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

Parameter accessLevel enum values Access level of sharing link to create (view or edit)
View Creates a read-only link to the item.
Edit Creates a read-write link to the item.

Example

Request

POST ../api/v1.0/me/notes/sectionGroups/{sectiongroup-id}/Microsoft.OneNote.Api.GetOrCreateAnonymousSharingLink 
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

Response

HTTP/1.1 200 Ok

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Edm.String",
  "value":"https://www.contoso.com/_layouts/15/WopiFrame.aspx?folderid=084a6fcc95ab54a678257e1b9cba41e7e&authkey=AXXriBu-O475sT4tfJeJDkA&FixProgId=1"
}

Request and response information

The following information applies to POST /GetOrCreateAnonymousSharingLink 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, or Notes.ReadWrite.All


Response data Description
Success code A 200 HTTP status code.
Response body An OData representation of the value 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.

Follow these steps to revoke an existing sharing link for a section group.

DELETE ../v1.0/me/notes/sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.RevokeAnonymousSharingLink

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

Parameter accessLevel enum values Access level of sharing link to create (view or edit)
View Creates a read-only link to the item.
Edit Creates a read-write link to the item.

Example

Request

DELETE ../v1.0/me/notes/sectiongroups/{sectiongroup-id}/Microsoft.OneNote.Api.RevokeAnonymousSharingLink
Authorization: Bearer {token}
Accept: application/json

{ 
  “accessLevel”: “view” 
}

Response

HTTP/1.1 204 No Content

Request and response information

The following information applies to DELETE /RevokeAnonymousSharingLink 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, or Notes.ReadWrite.All


Response data Description
Success code A 200 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.

Turn external sharing on or off for a SharePoint Online environment

Manage external sharing for your SharePoint Online environment

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 on a site in the tenant that the current user is signed in to. Only the current tenant is supported, accessed by using the myOrganization keyword.

Office 365 group notebooks

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. Office 365 groups (which return the unified groupType) are the only supported type of group. 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 that 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