Export (0) Print
Expand All
75 out of 108 rated this helpful - Rate this topic

Scopes and permissions

Scopes represent the various permission levels that an app can request from a user, in order to access the user's Microsoft account services data.

Before your app can make requests to the Live SDK APIs to work with services using Microsoft account, 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. For info about requesting a scope and obtaining user consent, see Obtaining user consent.

Scope types

There are two types of scopes:

  • Core scopes are central to the Live Connect APIs and involve users' core profile and contact data.
  • Extended scopes allow you to work with users' extended profile and contact data.

Top

Core scopes

ScopeEnables

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 Live Connect and is using your app.

wl.signin

Single sign-in behavior. With single sign-in, users who are already signed in to Live Connect are also signed in to your website.

 

Top

Extended scopes

ScopeEnables

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.

 

Top

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 scopeSuperset 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

 

Top

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 Live Connect looks like the following.

{
   "id": "8c8ce076ca27823f", 
   "name": "Roberto Tamburello", 
   "first_name": "Roberto", 
   "last_name": "Tamburello", 
   "gender": null, 
   "locale": "en_US"
}

As 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 the following.

http://blufiles.storage.msn.com/y1m9UZK4sELhooi0vvVFy0DvE0xIMPK-lZXeZQohhW9LmEXwLHZHyh9ue2c3oWnrTqx0r5q3J9N5KtFI58Rfy-u-Q

Top

Scope details

The following sections provide additional details about the available scopes.

In several of these sections, the Live Connect 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 objectStructure

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

 

Top

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 objectStructure

User

birth_day

User

birth_month

User

birth_year

 

Top

wl.calendars

The wl.calendars scope enables read access to a user's calendars and events.

Top

wl.calendars_update

The wl.calendars_update scope enables read and write access to a user's calendars and events.

Top

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 objectStructure

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.

Top

wl.contacts_create

The wl.contacts_create scope enables the creation of contacts in a user's address book.

Top

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.

Top

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.

Top

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.)

Top

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 objectStructure

User

emails

User

preferred (emails object)

User

account (emails object)

User

personal (emails object)

User

business (emails object)

 

Top

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.

Top

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 Live Connect and is using the app.

Top

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 objectStructure

User

phones

User

personal (phones object)

User

business (phones object)

User

mobile (phones object)

 

Top

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.

Top

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 objectStructure

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)

 

Top

wl.signin

The wl.signin scope enables single sign-in behavior. Users who are already signed in to Live Connect are also signed in to your app and therefore do not have to enter their credentials.

For info about the sign-in process, see Signing users in.

Top

wl.skydrive

The wl.skydrive scope enables read access to a user's files stored on OneDrive.

Top

wl.skydrive_update

The wl.skydrive_update scope enables read and write access to a user's files stored on OneDrive.

Top

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 objectStructure

User

work

User

employer (work array)

User

name (employer object)

User

position (work array)

User

name (position object)

 

Top

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

Connect to Outlook.com IMAP using OAuth 2.0

 

 

Show:
© 2014 Microsoft. All rights reserved.