The Windows Live™ Contacts API is an HTTP-based service that enables developers to programmatically submit queries to, and retrieve results from, the Windows Live Contacts Address Book database service.
In addition to a full contact management interface for a Windows Live user's address book, the Windows Live Contacts API provides a view to a subset of the Contact data for the purposes of sending Invitations.
Each view and set of abilities is controlled by the owner of the data, namely the Windows Live user who maintains the address book through products and applications in Windows Live, such as Windows Live Hotmail® and Windows Live Messenger.
Delegated Authentication
To gain access to a Windows Live user's data in the Live Contacts service, a third-party developer first must ask the owner for permission. This happens by presenting the Windows Live user with a Consent page driven by the third-party service requesting access to that user's data.
The type of access request is driven by providing the Windows Live ID Delegated Authentication service with an offer ID unique to the data being requested.
See Windows Live ID Delegated Authentication SDK for Application Providers for more information about how this is achieved.
The Windows Live user can accept or decline the request after signing into Windows Live. If the user accepts the request, then the consent is stored, and a consent token is returned to the calling third party.
Parts of the consent token are then used to construct the call to the Live Contacts API, which will return the data if all of the following are true:
-
the stored consent for the third party has not expired
-
the store consent for the third party has not been revoked by the Windows Live user
-
the delegation token is valid for the data being requested
-
the delegation token has not expired.
Windows Live Contacts Offers
As described above, to gain access to a Windows Live user's address book data, the owner must first consent to an access request based on the use to which the third party will put that data. Depending on the requirement, the third party may request access by providing the Delegated Authentication service for one or more of the following Offers.
|
Offer ID
|
Scope of Access
|
|---|
|
Contacts.Update
|
Update/add full contact information
|
|
Contacts.View
|
View full contact information
|
|
Contacts.Invite
|
View first name, last name, and preferred e-mail address
|
Please review the online documentation for the Delegated Authentication service and process before using the Windows Live Contacts service, because access is provided only through the use of the consent token returned from this process:
Windows Live ID Delegated Authentication SDK for Application Providers
Windows Live Contacts Service Requirements
The consent token returned from the Delegated Authentication service has two elements that are important to the construction of a call to the Windows Live Contacts service.
-
The Delegated Authentication token (DAT)
-
The Location ID (lid)
The consent token is URL encoded when returned, and typically would be unencoded first to break out the various parts of the consent token listed below.
The lid parameter taken from the consent token is used to identify which address book is to be accessed through the service, and therefore forms part of the service URL.
The DAT value is the token that authenticates the third-party calling application and is verified by the Live Contacts service against the stored user's consent records to ensure that the delegated authority is current and valid for the combination of the calling third party and the address book identified by the lid parameter.
The DAT value then is used to construct the HTTP Authorization Header for the call, in the following manner, for example:
Request.Headers.Add(“Authorization”, “DelegatedToken dt=\”” + DAT + “\””);
The value of this header will be the DAT originally returned by the consent process and must correspond with the user location identified by the request URI; otherwise the call will be rejected.
If the consent authorization or the DAT has expired, then the call will be rejected, and you will need either to request user consent again or renew the consent token.
Windows Live Contacts Service Entry Points
Using the Delegated Authentication service to obtain the consent token and using the DAT for the Authorization header, the Live Contacts service entry point is constructed using the value of the lid parameter from the consent token.
If the third-party application has requested access using the offer ID of Contacts.Invite, then the following service entry point is applicable and will apply only to the GET method:
https://livecontacts.services.live.com/users/@L@<lid>/rest/invitationsbyemail
If the third-party application has requested access using one of the other available Contacts offers, then the following service entry point provides access to the full Contacts schema:
https://livecontacts.services.live.com/users/@L@<lid>/rest/livecontacts
The <lid> part of the URL is the value of the lid parameter in the consent token returned from the Delegated Authentication service.
Note
Both entry points require an SSL connection. In order to increase security for user data, no alternative connection method is available.
Documentation Map
Additional Resources
See Also