Obtaining user consent (REST)

  • Article

This topic describes how an app requests permission from the user to access data that the user has stored on Microsoft OneDrive.

In this article
Prerequisites
Request initial scopes
Request additional scopes
Get a list of current permissions

In order for your app to access a user's data, the signed-in user must consent to letting the app access that data. The Live SDK divides this consent into categories, called scopes.

Some common scopes that your app might want to request are:

  • wl.basic Allows access to a user's basic info.

  • wl.emails Allows access to a user's email addresses.

  • wl.photos Allows access to a OneDrive user's photos.

Note

We recommend that you limit the number of scopes you request at any given time to the smallest number necessary to perform a task.

If a user chooses to use a feature that requires a scope that your app doesn't currently have permission to access, your app must get consent for the new scope from the user.

The Live SDK use OAuth 2.0 to enable users to sign in and provide consent to your app. When a user signs in to your app, he or she is redirected to a window that is hosted by the Microsoft account authorization web service.

After the user grants permission to access his or her data, your app can begin working with the user's information.

Prerequisites

The user must be signed in with a Microsoft account. To learn how to sign users in from your app, see Signing users in with REST.

Request initial scopes

You specify scopes in the initial call to the Live SDK authorization web service, where CLIENT_ID is the actual client ID, and REDIRECT_URL is either a custom redirect URL or https://login.live.com/oauth20\_desktop.srf, depending on your target OAuth grant flow. If you don't specify REDIRECT_URL, the value that was set in the redirect domain is used. For example, if the redirect domain is set to http://www.contoso.com in the app configuration and you don't specify REDIRECT_URL, then consent redirects to http://www.contoso.com#access_token=ACCESS_TOKEN.

https://login.live.com/oauth20_authorize.srf?client_id=CLIENT_ID&scope=wl.signin&response_type=RESPONSE_TYPE&redirect_uri=REDIRECT_URL

Note

Mobile apps should append &display=touch to the authorization URL.

You can request multiple scopes at a time. Each scope must be separated by a space, for example: wl.signin wl.basic. For REST, separate each scope with the escape character %20.

To learn more about scopes, see Scopes and permissions, which explains all the scopes that you can use with your app.

Request additional scopes

You must get a new access token that covers the additional scopes and any scopes that were consented to previously. You do this by specifying the list of scopes in a new call to the Live SDK authorization web service, like this.

https://login.live.com/oauth20_authorize.srf?client_id=CLIENT_ID&scope=wl.signin%20wl.basic&response_type=RESPONSE_TYPE&redirect_uri=REDIRECT_URL

Get a list of current permissions

To get a list of current permissions, make a GET request using the following URL, like this. Replace ACCESS_TOKEN with your app's access token.

GET https://apis.live.net/v5.0/me/permissions?access_token=ACCESS_TOKEN

The returned list of permissions will look similar to this. A "1" here represents a scope that the user has already consented to. (If a scope is not listed, the user hasn't consented to it for the app.)

{
    "data": [
        {
            "wl.basic": 1,
            "wl.signin": 1
        }
    ]
}