-->
Applies to: Consumer notebooks on OneDrive | Enterprise notebooks on Office 365
Thanks for the tips! I was having trouble signing in to Word, and I deleted the Microsoft User Data folder in my Documents folder, and also old copies of Office 2011 and Office X, and restarted the computer.
OneNote uses Microsoft account (formerly Live Connect) and Azure Active Directory to provide secure access to OneNote notebooks. Before you can access notebooks, you first need to authenticate using Microsoft account or Azure AD and get an access token.
Microsoft account is used to access consumer notebooks on OneDrive, and Azure AD is used to access enterprise notebooks on Office 365.
Both authorization services implement the OAuth 2.0 protocol to provide the access tokens that are required to interact with OneNote. All requests to the OneNote API must include a valid access token in the Authorization header.
- Select All Tasks, and then click Import. Follow the instructions in the wizard to import the certificate. Close the Group Policy window. Add the third party issuing the CA to the NTAuth store in Active Directory. The smart card logon certificate must be issued from a CA that is in the NTAuth store.
- Microsoft retired the configurable token lifetime feature for refresh and session token lifetimes on January 30, 2021 and replaced it with the Conditional Access authentication session management feature. Before enabling Sign-in Frequency, make sure other reauthentication settings are disabled in your tenant.
This article describes the auth-related processes that you're responsible for: Registering your app to get a client ID, specifying the permissions you need, and calling the authorization service to sign users in and get an access token.
Depending on your platform, you might be able to use an SDK to simplify the auth flows.
Note
OneNote will eventually support the single authentication model and app registration provided by the v2.0 app model. Watch for related updates on the OneNote Developer Blog.
Try the APIs
Follow the steps in this article to get an access token using your favorite network tool, such as Fiddler.
Authenticate using Microsoft account (consumer apps)
Register your application and get a client ID and secret (consumer apps)
To start, you need to register an application with Microsoft. This process creates a service principal that you link to from your app, and generates the client ID and secret that you send to the authorization service.
Do this if your app accesses consumer notebooks only, or if it accesses both consumer and enterprise notebooks.
Sign into the Microsoft account Developer Center with your Microsoft account. (If you're developing a Windows Store app, do this instead.)
If you don't have a Microsoft account, you'll need to create one. You should use an email address that you check regularly. We might try to contact you to highlight your app on our Featured Apps page, or if we notice unexpected network traffic coming from your app. We won't spam you or sell your information.
Choose Create application.
Enter the name you want users to see when they're prompted to grant permissions to your app, and choose the primary language for your app.
If you accept the terms of use and Privacy & Cookies policy, choose I accept to continue with the registration.
On the API Settings page, choose your app type and provide information about your app:
Web applications (server-side apps)
a. Choose No for Mobile or Desktop client app.
b. For the target domain, enter the service URL.
c. Enter the redirect URL where you want users directed to after they are authenticated and have granted access to your app.
Native applications (installed on a device)
a. Choose Yes for Mobile or Desktop client app.
b. (Optional) For the target domain, enter the mobile service URL.
c. (Optional) For the redirect URL, enter a valid URL. This acts as an identifier for your app, and doesn't have to be a physical endpoint.*
Save the client ID and client secret shown on the App Settings page and the redirect URL if you provided one.
Windows Store apps
If you're creating a Windows app, you'll register your application on the Windows Dev Center instead. This will provide you with the package identity (package SID) that you'll use instead of the client ID.
If you have multiple apps, you might need to override the default [JWT sharing behavior](http://msdn.microsoft.com/en-us/library/live/hh826544.aspx#restrict_jwt) on the Microsoft account Developer Center.-->Sign into the Windows Dev Center with your Microsoft account.
On the dashboard, choose Create a new app and enter your app name.
In Visual Studio, right-click your Windows Store app project and choose Store > Associate App with the Store.
In the Associate Your App with the Windows Store window, sign in with your Microsoft account, choose your app, and then choose Next > Associate. This adds the required Windows Store registration information to the application manifest.
For a universal Windows app, repeat the previous two steps for the Windows Phone project.
Choose OneNote permission scopes (consumer apps)
Permission scopes represent levels of access to OneNote content. You request the permissions that your app needs, and users grant or deny access when they sign into your app. Users can only grant permissions that they have.
Choose the lowest level of permissions that your app needs to do its work. You can request multiple scopes.
| Scope (consumer) | Description |
|---|---|
| office.onenote_create | Can view a list of the user's OneNote notebooks and create new pages, but cannot view or edit existing pages. Can enumerate the user's notebook hierarchy and create pages in any location. |
| office.onenote_update_by_app | Can create, view, and modify all pages created by the app. |
| office.onenote_update | Can create, view, and modify any content in the user's OneNote notebooks and pages. |
| office.onenote | Can view OneNote notebooks and pages but not modify them. |
| wl.signin | A Microsoft account permission scope. Allows your application to take advantage of single sign-on capabilities. |
| wl.offline_access | A Microsoft account permission scope. Allows your application to receive a refresh token so it can work offline even when the user isn't active. This scope is not available for the token flow. |
For permissions used to access Office 365 notebooks, see Choose OneNote permissions (enterprise apps).
Sign users in and get an access token (consumer apps)
Your app initiates the sign-in process by contacting the authorization service. If users aren't already signed in or haven't already consented, the service prompts them for credentials and to consent to the permissions requested by your app. If authentication and authorization are successful, you'll receive an access token that you include in your requests to the OneNote API.
Important
Treat access tokens and refresh tokens as securely as you would a user's password.
Note
Depending on your platform, you might be able to use an SDK to simplify the auth flows.
Choose your authentication flow. Both are standard OAuth 2.0 flows.
| Flow | Description |
|---|---|
| Token flow | Gets an access token in one call. Useful for quick access, but doesn't provide a refresh token for long term access. Also called the Implicit flow. |
| Code flow | Gets an authorization code in the first call and exchanges the code for an access token in the second call. When used with the wl.offline-access permission scope, your application receives a refresh token that enables long-term access. Also called the Authorization code flow. |
Sign users in with the Token flow
Load the following URL request in a web browser or web-browser control.
| Required query string parameter | Description |
|---|---|
| response_type | The type of authentication flow you're using. In this case, token. |
| client_id | The client ID created for your application. |
| redirect_uri | The redirect URL you registered for your application. Mobile and desktop apps that didn't specify one can use this: https://login.live.com/oauth20_desktop.srf |
| scope | The scopes that your application requires. Example: office.onenote%20wl.sign-in |
Upon successful authentication and authorization, the web browser redirects to your redirect URL and appends access parameters to the URL. The parameters include the access_token and token_type, as shown in the following example. The access token is valid for the number of seconds specified in the expires_in property.
Sign users in with the Code flow
Getting an access token is a two-step process with the Code flow:
- Sign the user in and get an authorization code.
- Exchange the code for an access token.
Step 1. Sign the user in and get an authorization code. To start the sign-in process, load the following URL request in a web browser or web-browser control.
| Required query string parameter | Description |
|---|---|
| response_type | The type of authentication flow you're using. In this case, code. |
| client_id | The client ID created for your application. |
| redirect_uri | The redirect URL you registered for your application. Mobile and desktop apps that didn't specify one can use this: https://login.live.com/oauth20_desktop.srf |
| scope | The scopes that your application requires. Example: office.onenote wl.signin wl.offline_access |
Upon successful authentication and authorization, the web browser redirects to your redirect URL with a code parameter appended to the URL, as shown in the following example. Copy the code value to use in step 2. This code is valid for a few minutes.
Step 2. Exchange the authorization code for an access token and refresh token. Send the following HTTP request with a properly encoded URL string in the message body.
| Required body parameter | Description |
|---|---|
| grant_type | The grant type of the request. In this case, authorization_code. |
| client_id | The client ID created for your application. |
| client_secret | The client secret created for your application. |
| code | The code you received as a URL parameter in the previous step. |
| redirect_uri | The redirect URL for your application. This must match the redirect_uri in the first request. |
If successful, the response contains a JSON string that includes the access_token--and the refresh_token if you requested the wl.offline_access scope--as shown in the following example. The access token is valid for the number of seconds specified in the expires_in property.
Include the access token in your request to the OneNote API
All your requests to the OneNote API must send the access token as a bearer token in the Authorization header. For example, the following request gets five of your notebooks, sorted alphabetically by name:
Access tokens are only valid for an hour, so you'll need to get fresh tokens when they expire. You should check the token's expiration before using it, and get a new access token if needed. Users can remain signed in, and they don't have to consent to permissions again unless they sign out or revoke permissions.
Get a new access token after it expires (consumer apps)
You can request a new access token by using the refresh token or by repeating the auth process from the beginning.
Microsoft Onenote The Authentication Session Has Expired Code
When an access token expires, requests to the API return a 401 Unauthorized response. Your app should handle this response and check the token expiration before sending requests.
Send the following HTTP request with a properly encoded URL string in the message body.
You received a refresh token if you requested the wl.offline_access permission and used the Code flow.
| Required body parameter | Description |
|---|---|
| grant_type | The grant type of the request. In this case, refresh_token. |
| client_id | The client ID created for your application. |
| client_secret | The client secret created for your application. |
| redirect_uri | The redirect URL for your application. This must match the redirect_uri that you used to obtain the tokens. |
| refresh_token | The refresh token you received previously. |
If successful, the response for the POST request contains a JSON string that includes the access_token and refresh_token, as shown in the following example.
Update your stored tokens to ensure that your app has tokens with the longest lifespan.
Sign users out (consumer apps)
To sign a user out, perform the following steps:
Delete any cached access tokens or refresh tokens you've received or stored.
Perform any sign out actions in your application (for example, cleaning up local state, removing any cached items, etc.).
Make a call to the authorization service using this URL:
This call removes any cookies that enable single sign-on and ensures that the user will be prompted to sign in.
| Required query string parameter | Description |
|---|---|
| client_id | The client ID value created for your application. |
| redirect_uri | The redirect URL for your application. This must match the redirect_uri that you used to obtain the tokens. |
After removing cookies, the browser redirects to your redirect URL. The redirect page loads without specifying any authentication query string options, which means the user has been logged out.
Revoke access
Users can revoke an application's access to their account by visiting the Microsoft account Manage page.
When consent for your app is revoked, any refresh token previously provided to your application will no longer be valid. You'll receive the following response if you try to refresh the token:
You'll need to repeat the auth flow to request a new access and refresh token from the beginning.
Authenticate using Azure AD (enterprise apps)
If your application uses application permissions (as opposed to delegate permissions), see OneNote Authentication and Azure AD application permissions.
Register your application and get a client ID and secret (enterprise apps)
To start, you need to register an application with Microsoft. This process creates a service principal that you link to from your app, and generates the client ID and secret that you send to the authorization service.
Do this if your app accesses enterprise notebooks only, or if it accesses both consumer and enterprise notebooks.
To register your app on an Azure AD tenant that's associated with an Office 365 subscription, you'll need to:
Get an Office 365 account with global administrator permissions to an Office 365 tenant
You can try or buy an Office 365 Developer subscription, or subscribe to a qualifying plan.
Provision OneDrive for Business for your tenant
This makes the OneNote application available so you can specify OneNote permissions. To check whether OneDrive for Business is provisioned, sign into OneNote Online with your Office 365 credentials (a work or school account like
someone@example.comorsomeone@example.onmicrosoft.com).If you see your notebooks, you're all set. If you see 'Sorry, we can't seem to get your notebooks...', choose Go to my account > Next. When your OneDrive for Business page loads, go back and refresh OneNote Online to complete the provisioning.
Note
Your users' personal sites must be provisioned before you can access their notebooks. The OneNote API will attempt to auto-provision their sites if needed.
Associate your Office 365 subscription with an Azure subscription
This allows you to register and manage your app in Azure AD. (learn more)
If you don't have an Azure subscription, do Option 1 in the next section. If you do have one, do Option 2.
Important
You and your users must have an Office 365 account with a valid Office 365 license. User accounts without valid licenses won’t be able to see any notebooks on OneNote Online, and API calls to their notebooks will fail. Office 365 admins can check status and assign unassign licenses.
Note
MSDN subscribers: You may be eligible for a free Office 365 Developer subscription, as well as added savings when you activate your Azure benefit. Check your benefits on the MSDN subscriptions page.
Associate your Azure subscription with your Office 365 subscription
Option 1: Sign up for an Azure subscription using admin credentials for your Office 365 subscription. Do this if you don't have an Azure subscription. This process associates the subscriptions.
Sign into the Azure Management Portal with your Office 365 admin credentials (a work or school account like
someone@example.comorsomeone@example.onmicrosoft.com).On the No subscriptions found page, choose Sign up for Microsoft Azure. The Sign up page will load, showing some information from your Office 365 subscription. This account will become a service administrator for the new Azure subscription.
The Sign up experience depends on whether you have a trial or paid Office 365 subscription:
If you have a trial subscription, enter your payment information on the Free Trial page. You won't be charged unless you decide to change to a paid subscription.
If you agree to the subscription agreement, offer details, and privacy statement, check the box and choose Purchase. The Subscriptions page for your new Azure account opens. Trial subscriptions are issued a $200.00 credit that can be used within 30 days. You can cancel the subscription from this page at any time.
If you have a paid subscription, complete your contact information and then choose Sign up. After your subscription is created, choose Start managing my service to open the Azure Management Portal.
Option 2: Associate an existing Azure subscription with an Office 365 subscription. Do this you have a Microsoft account that is a service administrator or co-administrator for your Azure subscription. This process makes the Microsoft account a global administrator of the Office 365 tenant.
Fix Issues When You Can't Sync OneNote - Office Support
Sign into the Azure Management Portal with your Microsoft account credentials (such as
someone@live.com).In the drawer at the bottom of the page, choose New > App services > Active Directory > Directory > Custom Create.
In the Add directory window, choose Use existing directory for the directory.
Choose I am ready to be signed out now, and click the check mark. This signs you out of the portal.
Sign back in using the global admin credentials for the Office 365 tenant that you want to associate (a work or school account like
someone@example.comorsomeone@example.onmicrosoft.com).When asked whether to use the directory with Azure, choose continue > Sign out now.
Close the browser and then reopen the Azure Management Portal.
Sign in again with your Microsoft account credentials, and choose Active Directory in the navigation pane. Your Office 365 directory should be listed on the Directory tab.
Register your app on the Azure Management Portal
Sign in to the Azure Management Portal. Use the admin credentials for your Azure subscription.
In the navigation pane, choose Active Directory.
Choose the directory where you want to register your application, and then open the Applications tab.
In the drawer at the bottom of the page, choose Add > Add an application my organization is developing.
Enter a friendly name for the application and choose the application type:
Web application or web API (browser-based or server apps)
a. Choose Web application and/or web API.
b. For the sign-on URL, enter the URL where users sign in and use your app.
c. For the app ID URI, enter a unique identifier for your app. This must be in a verified custom domain.
d. For the reply URL, enter the URL to redirect to in response to an OAuth 2.0 request. This doesn't have to be a physical endpoint, but it must be a valid URI.
e. To make the app available to external Azure tenants, choose Yes for Application is multi-tenant.
Native client application (apps installed on a device)
a. Choose Native client application.
b. Enter a redirect URI to redirect to in response to an OAuth 2.0 request. This doesn't have to be a physical endpoint, but it must be a valid URI.
For web apps, Azure generates both a client ID and app secret (or key). For native client apps, Azure generates a client ID. Save these values.
See the Office 365 documentation for detailed instructions about registering apps.
Choose OneNote permission scopes (enterprise apps)
Permission scopes represent levels of access to OneNote content. You request the permissions that your app needs, and users grant or deny access when they sign into your app. Users can only grant permissions that they have.
In the Azure Management Portal, in the Permissions to other applications section of the app configuration page, choose Add application.
Choose the OneNote application, and then click the check mark in the lower-right corner. If OneNote isn't listed, make sure you've provisioned OneDrive for Business for your tenant.
Choose the lowest level of permissions that your app needs to do its work, and save your changes. You can request multiple scopes.
Scopes for personal notebooks that are owned by the current user
If you're only working with personal notebooks on OneDrive for Business, choose from the following scopes.
| Scope (enterprise) | Permission in Azure portal | Description |
|---|---|---|
| Notes.Create | Create pages in OneNote notebooks | Can view the titles of your notebooks and sections; create new pages in any location. Cannot view or edit existing pages. |
| Notes.ReadWrite.CreatedByApp | Application-only OneNote notebook access | Can view the titles of your notebooks and sections; create new pages; rename sections; view and modify pages created by the app. Cannot view or modify pages created by other apps or in password protected sections. |
| Notes.Read | View OneNote notebooks | Can view the contents of your notebooks and sections. Cannot create new pages; modify existing pages; access password protected sections. |
| Notes.ReadWrite | View and modify OneNote notebooks | Can view the titles of your notebooks and sections; view and modify all your pages; create new pages; rename sections. Cannot access password protected sections. |
Scopes for site and group notebooks that the current user can access
If you're working with SharePoint site notebooks or unified group notebooks, choose from the following scopes. These permissions also apply to the current user's personal notebooks, but not to personal notebooks that are shared by other users. Accessing shared personal content is currently not supported.
| Scope (enterprise) | Permission in Azure portal | Description |
|---|---|---|
| Notes.Read.All | View OneNote notebooks in your organization | Can view the contents of notebooks and sections in all notebooks that the signed-in user has access to. Cannot create new pages; modify existing pages; access password protected sections. |
| Notes.ReadWrite.All | View and modify OneNote notebooks in your organization | Can view the titles of notebooks and sections; view and modify all pages; rename all sections; create new pages in all notebooks that the signed-in user has access to. Cannot access password protected sections. |
For permissions used to access personal notebooks on OneDrive, see Choose OneNote permissions (consumer apps).
Sign users in and get an access token (enterprise apps)
Your app initiates the sign-in process by contacting the authorization service. If users aren't already signed in or haven't already consented, the service prompts them for credentials and to consent to the permissions requested by your app. If authentication and authorization are successful, you'll receive an access token that you include in your requests to the OneNote API.
Important
Treat access tokens and refresh tokens as securely as you would a user's password.
Note
Depending on your platform, you might be able to use an SDK to simplify the auth flows.
Getting an access token is a two-step process:
- Sign the user in and get an authorization code.
- Exchange the code for an access token.
This process represents the Authorization Code Grant Flow. If you want to use the implicit flow, you'll need to edit the manifest file. See Configure your app to allow the OAuth 2.0 implicit grant flow in Register your brower-based web app.
Step 1. Sign the user in and get an authorization code. To start the sign-in process, load the following URL request in a web browser or web-browser control.
The URL below uses the common tenant endpoint, which is valid for any application.
| Required query string parameter | Description |
|---|---|
| response_type | The type of authentication flow you're using. In this case, code. |
| client_id | The client ID created for your application. |
| redirect_uri | The redirect URL for your application. |
| resource | The resource you need access to. In this case, https://onenote.com/ |
Upon successful authentication and authorization, the web browser redirects to your redirect URI with a code parameter appended to the URL, as shown in the following example.Copy the code value to use in step 2. This code is valid for a few minutes.
Step 2. Exchange the authorization code for an access token and refresh token. Send the following HTTP request with a properly encoded URL string in the message body.
| Required body parameter | Description |
|---|---|
| grant_type | The grant type of the request. In this case, authorization_code. |
| client_id | The client ID created for your application. |
| client_secret | Web applications and web APIs only. The client secret created for your application. |
| code | The code you received as a URL parameter in the previous step. |
| redirect_uri | The redirect URL for your application. This must match the redirect_uri in the first request. |
| resource | The resource you need access to. In this case, https://onenote.com/ |
If successful, the response contains a JSON string that includes the access_token and refresh_token, as shown in the following example. The access token is valid for the number of seconds specified in the expires_in property.
See Authorization Code Grant Flow to learn more about the Azure AD implementation of the code grant flow, including the additional parameters you can use in the requests.
Include the access token in your request to the OneNote API
All your requests to the OneNote API must send the access token as a bearer token in the Authorization header. For example, the following request gets five of your notebooks, sorted alphabetically by name:
Access tokens are only valid for an hour, so you'll need to get fresh tokens when they expire. You should check the token's expiration before using it, and get a new access token if needed. Users can remain signed in, and they don't have to consent to permissions again unless they sign out or revoke permissions.
Get a new access token after it expires (enterprise apps)
You can request a new access token by using the refresh token or by repeating the auth process from the beginning.
When an access token expires, requests to the API return a 401 Unauthorized response. Your app should handle this response and check the token expiration before sending requests.
Send the following HTTP request with a properly encoded URL string in the message body.
The URL in the following example uses the common tenant endpoint, which is valid for any application.
| Required body parameter | Description |
|---|---|
| grant_type | The grant type of the request. In this case, refresh_token. |
| client_id | The client ID created for your application. |
| client_secret | Web applications and web APIs only. The client secret created for your application. |
| redirect_uri | The redirect URL for your application. |
| refresh_token | The refresh token you received previously. |
| resource | The resource you need access to. In this case, https://onenote.com/ |
If successful, the response for the POST request contains a JSON string that includes the access_token and refresh_token, as shown in the following example.
Update your stored tokens to ensure that your app has tokens with the longest lifespan.
SDKs for OneNote development
OneNote apps can use the OneDrive API SDK to get the access tokens that are required for all requests to the OneNote API. The SDK makes authentication easier for you. You just provide your identity information and integrate a few calls, and the SDK handles everything from sign in and consent to getting, storing, and refreshing tokens. Then, you can make REST calls to the OneNote API. Our iOS tutorial shows how you can use the SDK in a OneNote app.
All versions of the SDK support Microsoft account authentication (for consumer notebooks), and some also support Azure Active Directory (for enterprise notebooks). See the OneDrive documentation for the current list of supported platforms.
Note
The OneDrive API SDK replaces the Live SDK. The Live SDK is deprecated but will continue to support existing OneNote applications that use it. For new development, use the OneDrive API SDK.
At some point, we may provide libraries that both handle authentication and support native calls to the OneNote API, but for now you can use the OneDrive API SDK.
Alternatively, enterprise apps can use the Active Directory Authentication Library (ADAL) to access Office 365 and SharePoint-hosted notebooks. You might consider using ADAL directly if there's no SDK available for your platform or if you want more control over the auth process. Our ASP.NET MVC tutorial shows how you can use ADAL in a OneNote app.
Important
To interact with OneNote content and resources, you should always use the OneNote API. Don't use the OneDrive API.
Errors
If there are errors with authentication, the web browser is redirected to an error page. The error page presents an end-user friendly message, but the URL for the page includes additional parameters that may help you debug what happened. The URL parameters are included as a bookmark, for example: #error={error_code}&error_description={message}
If the user chooses not to provide consent to your application, the flow will redirect to your redirect URL and include the error parameters.
For detailed information about handling errors, see Error Handling in OAuth 2.0.