Migrating from Tokens to Keys

Important

On March 30, 2012, the Bing Maps Token Service will be retired. If you are an existing customer using tokens, follow the steps in this topic to update your application to use Bing Maps Keys before this date.

Using a Bing Maps Key in your code is the recommended method of authenticating your Bing Maps application. Unlike tokens, keys do not expire, and a service request is not required to obtain a key. In short, it is much easier to authenticate your application using a Bing Maps Key. This topic outlines how to migrate code that currently uses the Bing Maps Token Service for authentication to code that uses a Bing Maps Key.

Get a Bing Maps Key

Before you change any code for any Bing Maps API application, you first need to get a Bing Maps Key. Go to the Bing Maps Account Center to create an account and get a key. This is described in Creating a Bing Maps Account and Getting a Bing Maps Key. You can use the same Windows Live ID to log in to the Bing Maps Account Center as you use to log in to the Bing Maps Customer Services site.

Note

If you are an existing licensed Bing Maps for Enterprise customer, be sure to provide your newly created Bing Maps Account ID to your Bing Maps Sales Representative, so that your newly created Bing Maps Account can be linked to your Bing Maps for Enterprise agreement. If you don’t know who your Bing Maps Sales Representative is, please contact the Bing Maps Licensing Team here.

You can track the Bing Maps API usage associated with a Bing Maps Key. Information on usage reporting is in the Understanding Bing Maps Transactions topic.

There are three more sections in this topic: Bing Maps AJAX Control (Version 6.3 or earlier), Bing Maps Silverlight Control, and Bing Maps SOAP Services. Each section outlines how to migrate the corresponding Bing Maps API code from using tokens to keys.

Bing Maps AJAX Control (Version 6.3 or earlier)

Note

If you are using Bing Maps AJAX Control 6.3 or earlier, consider upgrading to the latest Bing Maps AJAX Control, Version 7.0 as you update your code to use a Bing Maps Key. Information about using a Bing Maps Key in the version 7.0 map control is found in the Loading the AJAX Map Control topic.

If you are using the Bing Maps Token Service to retrieve tokens to authenticate your Bing Maps AJAX Control client application, your code will be simplified when you switch to using a Bing Maps Key.

First, remove all code that makes service requests to the Bing Maps Token Service. If you call the Token Service from server-side code, you can also remove any server-to-client code, such as client-side code that retrieves a server variable containing the token.

Next, in your client-side Java Script map control code, use the VEMap.SetCredentials Method instead of the VEMap.SetClientToken method to authenticate your map application. Pass your Bing Maps Key to the SetCredentials method. Your previous code may have looked like this:

var token = "<%=clienttoken %>";
var map = new VEMap(‘mymap’);
map.SetClientToken(token);
map.LoadMap();

Now it should look like this:

var key = "My Bing Maps Key";
var map = new VEMap(‘mymap’);
map.SetCredentials(key);
map.LoadMap();

Replace My Bing Maps Key with the key you created on the Create or view keys page in the Bing Maps Account Center.

Bing Maps Silverlight Control

If you are using the Bing Maps Token Service to retrieve tokens that you use to authenticate your Bing Maps Silverlight Control application, it is easy to convert to using a Bing Maps Key instead.

First, remove all code that makes service requests to the Bing Maps Token Service.

Next, in your Silverlight map control code-behind, use the ApplicationIdCredentialsProvider Class instead of the ClientTokenCredentialsProvider Class to manage your credentials. ApplicationIdCredentialsProvider has a property called ApplicationId Property that contains a Bing Maps Key.

Alternatively, set your Bing Maps Key in XAML instead. Your new XAML looks like this:

<UserControl x:Class="SilverlightApplication1.MainPage"
    xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml" 
    xmlns:m="clr-namespace:Microsoft.Maps.MapControl;assembly=Microsoft.Maps.MapControl"
    Width="1024" Height="768">
    <Grid x:Name="LayoutRoot" Background="White">
        <m:Map x:Name="myMap" CredentialsProvider="Your Bing Maps Key" Mode="Road"/>
    </Grid>
</UserControl>

Replace Your Bing Maps Key with the key you created on the Create or view keys page in the Bing Maps Account Center.

Bing Maps SOAP Services

If you are using the Bing Maps Token Service to retrieve tokens that you use to authenticate your Bing Maps SOAP Services application, simplify your code by using a Bing Maps Key instead.

First, remove all code that makes service requests to the Bing Maps Token Service.

Next, use the Credentials.ApplicationId Property to set a Bing Maps Key instead of using the Credentials.Token Property.

Previous geocode service request code may have looked like this:

// Get a token before making a request
string token = GetToken();

GeocodeService.GeocodeRequest geocodeRequest = new GeocodeService.GeocodeRequest();

// Set the credentials using a valid Bing Maps token
geocodeRequest.Credentials = new GeocodeService.Credentials();
geocodeRequest.Credentials.Token = token;

                // Set the full address query
                geocodeRequest.Query = "1 Microsoft Way, Redmond, WA";

                // Make the geocode request
                GeocodeService.GeocodeServiceClient geocodeService = new GeocodeService.GeocodeServiceClient();
                GeocodeService.GeocodeResponse geocodeResponse = geocodeService.Geocode(geocodeRequest);

Your new code using a Bing Maps Key looks like this:

string key = "Bing Maps Key";

GeocodeService.GeocodeRequest geocodeRequest = new GeocodeService.GeocodeRequest();

// Set the credentials using a valid Bing Maps Key
geocodeRequest.Credentials = new GeocodeService.Credentials();
geocodeRequest.Credentials.ApplicationId = key;

// Set the full address query
geocodeRequest.Query = "1 Microsoft Way, Redmond, WA";

// Make the geocode request
GeocodeService.GeocodeServiceClient geocodeService =
new GeocodeService.GeocodeServiceClient("BasicHttpBinding_IGeocodeService");
GeocodeService.GeocodeResponse geocodeResponse = geocodeService.Geocode(geocodeRequest);

Replace Bing Maps Key with the key you created on the Create or view keys page in the Bing Maps Account Center.