Scopes and permissions

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

• Core scopes

• Extended scopes

• Subset and superset behavior

• Accessing a user's public info

• Scope details

• Related topics

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
wl.basic	Read access to a user's basic profile info. Also enables read access to a user's list of contacts.
wl.offline_access	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.
wl.signin	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
wl.birthday	Read access to a user's birthday info including birth day, month, and year.
wl.calendars	Read access to a user's calendars and events.
wl.calendars_update	Read and write access to a user's calendars and events.
wl.contacts_birthday	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.
wl.contacts_create	Creation of new contacts in the user's address book.
wl.contacts_calendars	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.
wl.contacts_photos	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.
wl.contacts_skydrive	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.
wl.emails	Read access to a user's personal, preferred, and business email addresses.
wl.events_create	Creation of events on the user's default calendar.
wl.imap	Read and write access to a user's email using IMAP, and send access using SMTP.
wl.phone_numbers	Read access to a user's personal, business, and mobile phone numbers.
wl.photos	Read access to a user's photos, videos, audio, and albums.
wl.postal_addresses	Read access to a user's postal addresses.
wl.skydrive	Read access to a user's files stored in OneDrive.
wl.skydrive_update	Read and write access to a user's files stored in OneDrive.
wl.work_profile	Read access to a user's employer and work position information.
office.onenote_create	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)

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.

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.

wl.contacts_skydrive

The wl.contacts_skydrive scope enables read access to OneDrive files that other users have shared with the user.

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.

Related topics

• REST reference

• OAuth 2.0