Authenticate the user

Authenticate the user for the OneNote API

Learn how to use the Microsoft Live SDK and libraries to authenticate users in apps that use the Microsoft OneNote API.

Last modified: January 22, 2016

Applies to: OneNote service

In this article
Authenticate the user in an Android app
Authenticate the user in an iOS app
Authenticate the user in a Windows Phone app
Authenticate the user in a Windows Store app
Authenticate the user with REST

Note Note

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

The OneNote API requires your app ask for specific permissions when it authenticates to the user's Microsoft account. After the user grants permissions, the app receives an OAuth token that it sends with each request to the OneNote API. Access tokens typically expire in an hour, but in most cases the app can refresh them for up to a year before it has to ask the user for permissions again. Using the Live SDK makes this process simple to program, and provides a consistent experience for your users.

The Live SDK provides complete information for learning and using the OAuth-based sign-in process in your apps. If you're not familiar with the Live SDK, you can learn more in the Core Concepts documentation. If you're overwhelmed by terms used in the Live Connect Developer Center, take a few moments to read our Introduction to OAuth.

As you build your OneNote API app, you will likely not need to do a whole lot of customization to the code examples from the Live SDK; the integration is designed to be easy. However, you'll need to pass specific scope names when your app requests permission from the user.

OneNote permission scopes provide varying levels of access to OneNote content, so your app can request just the access it needs. For more information, see OneNote permission scopes.

Because access tokens are only valid for about an hour, we recommend that you also request the wl.offline_access scope and use refresh tokens. A refresh token lets you obtain a new access token without prompting the user to grant permissions again. Refresh tokens are valid for up to a year, or until the user revokes their permission from the app. You can find more in-depth information in the Live Connect Developer Center Scopes and permissions documentation.

The following sections contain links to platform-specific libraries, documentation, and code examples that show how to get and use the OAuth token in your OneNote apps. In addition, you can find all the Live SDK samples on GitHub at https://github.com/liveservices/LiveSDK.

Use the following resources to learn about using Microsoft Live authentication in your Android app.

This code example gets the access token from a Live Connect session, and then later uses it in the Authorization header of an HttpsURLConnection request named mUrlConnection.

mAccessToken = session.getAccessToken();
    ...
mUrlConnection.setRequestProperty("Authorization", "Bearer " + mAccessToken);

Use the following resources to learn about using Microsoft Live authentication in your iOS app:

This code sample shows how to add the Bearer token into a OneNote API request named request, which is a NSMutableURLRequest. The code retrieves the token directly from the liveClient.session object.


  [request setValue:[@"Bearer " 
  stringByAppendingString:liveClient.session.accessToken] 
  forHTTPHeaderField:@"Authorization"];

Use the following resources to learn about using Microsoft Live authentication in your Windows Phone app:

This code sample shows how to retrieve the m_AccessToken Bearer token, and add it into a OneNote API request named httpClient, which is an HttpClient object.


  m_AccessToken = e.Session.AccessToken;

  httpClient.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", m_AccessToken);

Use the following resources to learn about using Microsoft Live authentication in your Windows Store app:

This code sample shows how to retrieve the m_AccessToken Bearer token, and add it into a OneNote API request named httpClient, which is an HttpClient object.


  m_AccessToken = e.Session.AccessToken;

  httpClient.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", m_AccessToken);

Use the following resources to learn about using Microsoft Live authentication in your REST-based application. Although developing a Web app that uses REST directly is more complex than doing a native-client app, the Live Connect Developer Center provides complete information and samples to help:

This code sample shows the headers for a REST request to create a new page. Replace tokenString with the Bearer token your app obtains from the Live REST endpoint during login.


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

Content-Type:text/html 
Authorization:Bearer tokenString

Show:
© 2016 Microsoft