Scopes and permissions
Important
This content is archived. For current information about OneDrive scopes, see Authentication scopes.
Scopes represent the various permission levels that an app can request from a user, in order to access the user's OneDrive data.
Before your app can make requests to the Live SDK APIs to work with OneDrive, you must get permission from the user. In the Live SDK APIs, this permission is called a scope. Each scope grants a different permission level. You'll find more info about each scope in this topic.
Scope types
There are two types of scopes:
Core scopes are central to the Live SDK APIs, and involve users' core profile and contact data.
Extended scopes allow you to work with users' extended profile and contact data.
Core scopes
Scope |
Enables |
---|---|
Read access to a user's basic profile info. Also enables read access to a user's list of contacts. |
|
The ability of an app to read and update a user's info at any time. Without this scope, an app can access the user's info only while the user is signed in to their Microsoft account and is using your app. |
|
Single sign-in behavior. With single sign-in, users who are already signed in to their Microsoft account are also signed in to your website. |
Extended scopes
Scope |
Enables |
---|---|
Read access to a user's birthday info including birth day, month, and year. |
|
Read access to a user's calendars and events. |
|
Read and write access to a user's calendars and events. |
|
Read access to the birth day and birth month of a user's contacts. Note that this also gives read access to the user's birth day, birth month, and birth year. |
|
Creation of new contacts in the user's address book. |
|
Read access to a user's calendars and events. Also enables read access to any calendars and events that other users have shared with the user. |
|
Read access to a user's albums, photos, videos, and audio, and their associated comments and tags. Also enables read access to any albums, photos, videos, and audio that other users have shared with the user. |
|
Read access to Microsoft OneDrive files that other users have shared with the user. Note that this also gives read access to the user's files stored in OneDrive. |
|
Read access to a user's personal, preferred, and business email addresses. |
|
Creation of events on the user's default calendar. |
|
Read and write access to a user's email using IMAP, and send access using SMTP. |
|
Read access to a user's personal, business, and mobile phone numbers. |
|
Read access to a user's photos, videos, audio, and albums. |
|
Read access to a user's postal addresses. |
|
Read access to a user's files stored in OneDrive. |
|
Read and write access to a user's files stored in OneDrive. |
|
Read access to a user's employer and work position information. |
|
Read and write access to a user's OneNote notebooks stored in OneDrive. |
Subset and superset behavior
Certain scopes give access to a subset of the data that is addressed by other scopes. For example, wl.birthday gives access to the user's birthday, but wl.contacts_birthday gives access both to the user's birthday and to birthdays of the user's contacts. In requests that specify multiple scopes, if one scope is a superset of another, the subset scope is ignored. Likewise, if an app has been granted access to a subset scope (for example, wl.birthday), and the user later grants access to a superset scope (for example, wl.contacts_birthday), the subset scope is revoked as redundant. The following table shows the scopes that share a subset/superset relationship.
Subset scope |
Superset scopes |
---|---|
wl.birthday |
wl.contacts_birthday |
wl.calendars |
wl.contacts_calendars wl.calendars_update |
wl.photos |
wl.contacts_photos |
wl.skydrive |
wl.contacts_skydrive wl.skydrive_update |
Accessing a user's public info
There is an exception to the rule that you must get the permission from the user before you can access his or her info: your app can access a user's publicly available info without requesting any scope. Public info includes the user's ID, first and last names, display name, gender, locale, and picture. For example, the following GET request, without any access token specified, returns the user's public profile info.
https://apis.live.net/v5.0/8c8ce076ca27823f
The info returned by the Live SDK looks like the following.
{
"id": "8c8ce076ca27823f",
"name": "Roberto Tamburello",
"first_name": "Roberto",
"last_name": "Tamburello",
"gender": null,
"locale": "en_US"
}
In another example, a GET request for the user's picture, also without any access token specified, looks like the following.
https://apis.live.net/v5.0/8c8ce076ca27823f/picture
The request would be redirected to a URL that might look like this.
http://blufiles.storage.msn.com/y1m9UZK4sELhooi0vvVFy0DvE0xIMPK-lZXeZQohhW9LmEXwLHZHyh9ue2c3oWnrTqx0r5q3J9N5KtFI58Rfy-u-Q
Scope details
The following sections provide additional details about the available scopes.
In several of these sections, the Live SDK Representational State Transfer (REST) objects and the corresponding structures that these scopes can access are described in tables. For more info about these REST objects and structures, see REST reference.
wl.basic
The wl.basic scope enables read access to a user's basic profile info and to the user's list of contacts.
The following table lists the structures that can be accessed with user consent to the wl.basic scope.
REST object |
Structure |
---|---|
User |
link |
User |
updated_time |
Contact |
id |
Contact |
first_name |
Contact |
last_name |
Contact |
name |
Contact |
gender |
Contact |
is_friend |
Contact |
is_favorite |
Contact |
user_id |
Contact |
email_hashes |
Contact |
birth_day (also requires the wl.contacts_birthday scope) |
Contact |
birth_month (also requires the wl.contacts_birthday scope) |
Contact |
updated_time |
wl.birthday
The wl.birthday scope enables read access to a user's birth-date info.
The following table lists the structures that can be accessed with user consent to the wl.birthday scope.
REST object |
Structure |
---|---|
User |
birth_day |
User |
birth_month |
User |
birth_year |
wl.calendars
The wl.calendars scope enables read access to a user's calendars and events.
wl.calendars_update
The wl.calendars_update scope enables read and write access to a user's calendars and events.
wl.contacts_birthday
The wl.contacts_birthday scope enables read access to birth-date info for a user's contacts.
The following table lists the structures that can be accessed with user consent to the wl.contacts_birthday scope.
REST object |
Structure |
---|---|
Contact |
birth_day (also requires the wl.basic scope) |
Contact |
birth_month (also requires the wl.basic scope) |
Note
When a user consents to the wl.contacts_birthday scope, the user also implicitly consents to access to the info that is covered by the wl.birthday scope. However, if the user consents to the wl.birthday scope and then later consents to the wl.contacts_birthday scope, the wl.birthday scope is revoked because it is a subset of wl.contacts_birthday and is therefore redundant.
wl.contacts_create
The wl.contacts_create scope enables the creation of contacts in a user's address book.
wl.contacts_calendars
The wl.contacts_calendars scope enables read access to a user's calendars and events, and read access to calendars and events that other users have shared with the user. Permissions to shared calendars and events are restricted by the permissions that have been granted to the consenting user.
Note
When a user consents to the wl.contacts_calendars scope, the user also implicitly consents to access to the info that is covered by the wl.calendars scope. However, if the user consents to the wl.calendars scope and then later consents to the wl.contacts_calendars scope, the wl.calendars scope is revoked because it is a subset of wl.contacts_calendars and is therefore redundant.
wl.contacts_photos
The wl.contacts_photos scope enables read access to a user's albums, photos, videos, and audio and to their associated comments and tags. This scope also enables read access to any albums, photos, videos, and audio that other users have shared with the user.
This scope enables read access to all of the structures of the Album, Audio, Photo, and Video objects for the user's contacts.
Note
When a user consents to the wl.contacts_photos scope, the user also implicitly consents to access to the info that is covered by the wl.photos scope. However, if the user consents to the wl.photos scope and then later consents to the wl.contacts_photos scope, the wl.photos scope is revoked because it is a subset of wl.contacts_photos and is therefore redundant.
wl.contacts_skydrive
The wl.contacts_skydrive scope enables read access to OneDrive files that other users have shared with the user.
Note
When a user consents to the wl.contacts_skydrive scope, the user also implicitly consents to access to the info that is covered by the wl.skydrive scope. However, if the user consents to the wl.skydrive scope and then later consents to the wl.contacts_skydrive scope, the wl.skydrive scope is revoked because it is a subset of wl.contacts_skydrive and is therefore redundant.)
wl.emails
The wl.emails scope enables read access to a user's email addresses.
The following table lists the structures that can be accessed with user consent to the wl.emails scope.
REST object |
Structure |
---|---|
User |
emails |
User |
preferred (emails object) |
User |
account (emails object) |
User |
personal (emails object) |
User |
business (emails object) |
wl.events_create
The wl.events_create scope enables the creation of events on the user's default calendar.
This scope enables access to all of the Event object's structures.
wl.imap
The wl.imap scope enables read and write access to a user's email using IMAP, and send access using SMTP.
To use this scope, you need to call the Microsoft Outlook.com APIs. For more information, see Connect to Outlook.com IMAP using OAuth 2.0.
wl.offline_access
The wl.offline_access scope enables an app to read and update a user's info at any time. Without this scope, an app can access the user's info only while the user is signed in to their Microsoft account, and is using the app.
wl.phone_numbers
The wl.phone_numbers scope enables access to a user's phone numbers.
The following table lists the structures that can be accessed with user consent to the wl.phone_numbers scope.
REST object |
Structure |
---|---|
User |
phones |
User |
personal (phones object) |
User |
business (phones object) |
User |
mobile (phones object) |
wl.photos
The wl.photos scope enables read access to a user's photos, videos, audio, and albums.
This scope enables read access to all of the structures of the Album, Audio, Photo, and Video objects for a user.
wl.postal_addresses
The wl.postal_addresses scope enables read access to a user's postal addresses.
The following table lists the structures that can be accessed with user consent to the wl.postal_addresses scope.
REST object |
Structure |
---|---|
User |
addresses |
User |
personal (addresses object) |
User |
street (personal object) |
User |
street_2 (personal object) |
User |
city (personal object) |
User |
state (personal object) |
User |
postal_code (personal object) |
User |
region (personal object) |
User |
business (addresses object) |
User |
street (business object) |
User |
street_2 (business object) |
User |
city (business object) |
User |
state (business object) |
User |
postal_code (business object) |
User |
region (business object) |
wl.signin
The wl.signin scope enables single sign-in behavior. Users who are already signed in to their Microsoft account are also signed in to your app and therefore do not have to enter their credentials.
wl.skydrive
The wl.skydrive scope enables read access to a user's files stored on OneDrive.
wl.skydrive_update
The wl.skydrive_update scope enables read and write access to a user's files stored on OneDrive.
wl.work_profile
The wl.work_profile scope enables read access to a user's employer and work position info.
The following table lists the structures that can be accessed with user consent to the wl.work_profile scope.
REST object |
Structure |
---|---|
User |
work |
User |
employer (work array) |
User |
name (employer object) |
User |
position (work array) |
User |
name (position object) |
office.onenote_create
The wl.office.onenote_create scope enables the creation of new pages in a user's OneNote notebooks on OneDrive, through the OneNote service API.