Acquiring a Verification Code

Acquiring a Verification Code

Current information about Live Connect is now available in the Windows Live Developer Center. The information in the following sections is provided for legacy purposes only.

Before your application can access a protected resource, such as a user's Windows Live contacts, it must acquire a verification code. This code indicates that a user has provided consent to your application for a specific set of offers and actions against a protected resource.

The following example shows a URL that enables a user to provide consent to an application by using a Windows Live ID. When successful, this URL returns the user to your application, along with a verification code.

The following table describes the elements in the verification code request.

Element Description

URL endpoint

Provides the Windows Live endpoint that processes the request. In most cases, this endpoint is


Contains the client ID that identifies your application. If you do not have a client ID, you can learn how to get one in the section, Getting Started with Messenger Connect.

A typical client ID resembles the following:



Provides the return URL to which the Windows Live service sends the verification code. The domain of this URL must match the domain that you provided when you created your client ID.

An example of a callback URL is


Contains one or more pairs of offers and actions. Each protected resource, such as Windows Live Messenger, has a specific set of offers and actions. An example of a scope is WL_Contacts.View.

You can submit multiple offers and actions in a comma-delimited list, and then add them to the wrap_scope parameter.

Acquiring a verification code is the first step your application must take when working with new users to access a protected resource, such as their contacts or email. This code does not enable your application to access those resources directly. Instead, your application uses the verification code to acquire an access token. Your application uses this access token to access a specific protected resource.

A verification code request requires three pieces of information: your client ID, a callback URL, and a set of offers and actions. You define these criteria in the wrap_client_id, wrap_callback, and wrap_scope parameters. Your application must use the correct values for these parameters. If the client ID in the request does not match the client ID that you created with Windows Live, the user sees a Windows Live error page. If the callback URL is incorrect, the user might get a HTTP 404 error.

When a user clicks the verification code link on your site, open the link in a pop-up window by using the following parameters:

  • Height=375
  • Width=465
  • Status=yes
  • Toolbar=no
  • Menubar=no
  • Location=yes
  • Resizable=yes
  • Scrollbars=yes

If the offers and actions are incorrect, the value that is specified in the wrap_callback parameter redirects the user to your site. In this scenario, the Windows Live service includes two error parameters: error_code and wrap_error_reason. These parameters are defined in the OAuth WRAP specification document. In the case of an invalid offer, these parameters contain the following information:

  • Error_code: 2020
  • Wrap_error_reason: OfferNotFoundEvent

Your application is responsible for handling these errors correctly.

Verification codes are valid for a maximum of 30 minutes. If your application attempts to use a verification code that has expired, the Windows Live service returns an HTTP 400 error. Consequently, your site must also handle this error type. In most cases, this scenario does not occur because a verification code is used immediately to acquire an access token. However, there are situations in which this error could occur, for example, if your application temporarily loses its ability to connect to the Windows Live service.

We recommend that all of your OAuth WRAP exchanges with the Windows Live consent service use Secure Sockets Layer (SSL) to help protect the integrity of the data you receive. If you are unable to use SSL, you must add a unique identifier to the wrap_callback parameter as a querystring parameter. This parameter must uniquely identify the user or the browser session.

You must provide this unique identifier twice: once for the verification code request, and again for the access token request. Do not copy the identifier from the verification code response.

See Consent Request Parameters for more information.

© 2015 Microsoft