Accessing Bing Webmaster APIs using OAuth 2.0
Bing Webmaster provides OAuth 2.0 support for its API to enable delegated access to registered site owner's data.
This page provides an overview and the detailed steps of the OAuth 2.0 authorization scenarios Bing supports, and provides links to more detailed content. For more details about using OAuth 2.0 protocol for authentication, see OAuth 2.0 protocol.
Overview
All applications follow a basic pattern when accessing a Bing Webmaster API using OAuth 2.0. First, the client application needs to register on Bing Webmaster portal to generate credentials (client ID and client secret).
These client credentials can be looked up any time from the API Access section in Bing Webmaster Account under Settings. Your client application needs to request a temporary access token from the Bing Webmaster Authorization Server, which can be used to access the Bing Webmaster API.
A request for access token for the first time requires obtaining an authorization code via an authentication step where the user logs in with their Bing Webmaster account. After logging in, the user is asked to grant one or more permissions that your application is requesting.
If the user grants the permission, the Bing Webmaster Authorization Server sends your application an authorization code that your application can use to obtain an access token and a refresh token. If the user does not grant the permission, the server returns an error.
Your application can now access user data by calling a Bing Webmaster API using the access token granted to you. Both Authorization code and access token remain valid for only for limited time to prevent security breaches. Upon the expiry of the access token, your application can request a new access token from Bing Webmaster using the refresh token granted in exchange of authorization code.
The list below summarizes these steps:
Your application registers on Bing Webmaster to generate its credentials.
Your application identifies the permissions it needs.
Your application redirects the user to Bing Webmaster authorization end point along with the list of requested permissions.
The user decides whether to grant the permissions to your application.
If the user granted the requested permissions, your application retrieves access token needed to make API requests on the user's behalf. A refresh token is also obtained in the same request which can be used to renew access token upon expiry.
The flowchart maps the entire process described above:
Detailed steps:
1. Generate OAuth 2.0 credentials
Follow the below instructions to generate OAuth 2.0 credentials such as a client ID and client secret that are known to both Bing Webmaster and your application:
Sign in to your account on Bing Webmaster Tools. In case you do not already have a Bing Webmaster account, sign up today using any Microsoft, Google or Facebook ID.
Click on Settings button on top right corner and then go to API Access section.
If you are using API Access for the first time, please read and accept the Terms and Conditions displayed and then click on OAuth Client.
Register OAuth client by filling the Client Name and Redirect URI fields as below descriptions:
Name: It will be user-facing display name for your application
Redirect URI: This is the path in your application that users are redirected to after they have authenticated with Bing Webmaster.
Select the created OAuth client name
Copy the client ID and client secret to your clipboard, as you will need them to configure in your application.
2. Set authorization parameters
Your application needs to create the authorization request which sets the parameters that identify your application and define the scope that the user will be asked to grant to your application.
The table below defines the authorization parameters for web server applications:
| Parameter | Value |
|---|---|
| client_id | The client ID for your application. You can find this value in your Bing Webmaster account in API Access section under Settings. |
| response_type | This field must contain the value: code |
| redirect_uri | The URI to redirect to after the user grants or denies permission. This URI needs to have been entered in the Redirect URI field that you specified when you registered your application. If this value doesn't match exactly (including upper or lowercase, terminating slashes, and such), you will get a redirect uri mismatch error. |
| scope | A space-separated list of scopes. See available scopes |
Scopes enable your application to only request access to the specific API endpoints on behalf of a user that it needs while also enabling users to control the amount of access that they grant to your application. We recommend that you identify the scopes that your app will need permission to access. See available scopes.
3. Redirect user to Bing Webmaster's OAuth 2.0 server
Your application must have user consent before it can execute a Bing Webmaster API request. Typically, this is done when your application needs to access the user's data for the first time. This step also occurs when your application first needs to access additional scope that it does not yet have permission to access.
To obtain user consent, redirect the user to /authorize endpoint of the Bing Webmaster service to initiate the authentication and authorization process:
GET https://www.bing.com/webmasters/OAuth/authorize
An example URL for client id as 449986cfb7504861996ba2f443210776 and redirect URI as https://example.com/callback is shown below, with line breaks and spaces for readability:
https://www.bing.com/webmasters/oauth/authorize?response_type=code&
client_id=449986cfb7504861996ba2f443210776&
redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&
scope=webmaster.manage
Note: You need to use your client id, redirect URI and scope.
The response is sent back to your application using the redirect URL you specified. The response is explained in next step.
4. Handling the OAuth 2.0 server response
After the user accepts, or denies your request, the Bing Webmaster redirects the user back to your redirect_uri. In this example, the redirect address is: https://example.com/callback
If the user approves the access request, then the response contains an authorization code. If the user does not approve the request, the response contains an error message. The authorization code or error message that is returned to the web server appears on the query string, as shown below:
A sample error response:
https://example.com/callback/auth?error=access_denied
A sample authorization code response:
https://example.com/callback/?code=L4yRDynJso8B9RqYT-a0B1Oct-FNxPzZWd9FfU07QWA
5. Request for access token and refresh token
When the authorization code has been received, you will need to exchange it with an access token by making a POST request to /token endpoint: Keep in mind authorization code is valid only for a duration of 5 minutes.
POST https://www.bing.com/webmasters/oauth/token
The body of this POST request must contain the following parameters encoded in ´application/x-www-form-urlencoded as defined in the OAuth 2.0 specification:
| Parameter | Value |
|---|---|
| client_id | The client ID for your application. You can find this value in your Bing Webmaster account in API Access section under Settings. |
| client_secret | The client secret for your application. You can find this value in your Bing Webmaster account in API Access section under Settings. |
| code | The authorization code returned from the initial request in previous step. |
| grant_type | This field must contain the value: authorization_code |
| redirect_uri | The URI to redirect to after the user grants or denies permission. This URI needs to have been entered in the Redirect URI field that you specified when you registered your application. |
A sample request is shown below:
POST /webmasters/oauth/token HTTP/1.1
Host: www.bing.com
Content-Type: application/x-www-form-urlencoded
code= L4yRDynJso8B9RqYT-a0B1Oct-FNxPzZWd9FfU07QWA&
client_id= 449986cfb7504861996ba2f443210776 &
client_secret= SP313W-3hpgWXaq_S6P-J2-d1_xsLc4Fs…XOzHGQioA&
redirect_uri= https%3A%2F%2Fexample.com%2Fcallback &
grant_type= authorization_code
Bing Webmaster responds to this request by returning a JSON object that contains a short-lived access token and a refresh token. The response has the status code 200 OK in the response header, and the following JSON data in the response body:
| Parameter | Value |
|---|---|
| access_token | The token that your application will need to send to authorize a Bing Webmaster API request. |
| expires_in | The time period (in seconds) for which the access token is valid. |
| refresh_token | A token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access. |
| token_type | The type of token returned. This field's value is always set to Bearer. |
Note: Your application should save both tokens in a secure location that is accessible between different invocations of your application. The refresh token enables your application to obtain a new access token if the one that you have expires. As such, if your application loses the refresh token, the user will need to repeat the OAuth 2.0 consent flow so that your application can obtain a new refresh token.
A sample JSON response is shown below:
{
"access_token": "2w9TkmeeK5YNpeP…eDWXRkltW1hxFZyPuKXqQ",
"token_type": "bearer",
"expires_in": 3599,
"refresh_token": "eyJ0eXI7vgiEjC…zqoTD-MRJ9D8J06vp_39oWiA"
}
6. Use the access token to access the Bing Webmaster APIs
After receiving an access token, your application can use this token to make calls to a Bing Webmaster API on behalf of a given user account. To do this, include the access token in a request to the API by setting the Authorization HTTP header Bearer value to access token.
Shown below is a sample HTTP POST request to call the SubmitUrl API (with endpoint https://www.bing.com/webmaster/api.svc/json/SubmitUrl):
POST /webmaster/api.svc/json/SubmitUrl HTTP/1.1
Host: www.bing.com
Content-Type: application/json
Authorization: Bearer 2w9TkmeeK5YNpeP…eDWXRkltW1hxFZyPuKXqQ
{
"siteUrl":"https://www.example.com",
"url":"https://www.example.com/url1"
}
Note that you need to specify your own access token.
7. Request a new access token, if needed, using a refresh token
Access tokens have limited lifetimes and become invalid credentials for an API request upon expiry of their validity. Your application may obtain a new access token by sending the refresh token originally obtained during the authorization code exchange.
To get new access token, your application needs to send an HTTPS POST request to Bing Webmaster’s authorization server ( https://www.bing.com/webmasters/token) that includes the following parameters:
| Parameter | Value |
|---|---|
| client_id | The client ID for your application. You can find this value in your Bing Webmaster account in API Access section under Settings. |
| client_secret | The client secret for your application. You can find this value in your Bing Webmaster account in API Access section under Settings. |
| grant_type | This field must contain the value: authorization_code |
| refresh_token | The refresh token returned from the authorization code exchange |
A sample request is shown below:
POST /webmasters/token HTTP/1.1
Host: www.bing.com
Content-Type: application/x-www-form-urlencoded
client_id= 449986cfb7504861996ba2f443210776 &
client_secret= SP313W-3hpgWXaq_S6P-J2-d1_xsLc4Fs…XOzHGQioA&
refresh_token= eyJ0eXI7vgiEjC…zqoTD-MRJ9D8J06vp_39oWiA&
grant_type= refresh_token
If the user has not revoked the permission granted to share user data, the token server returns a JSON object that contains a new access token. The following snippet shows a sample response:
{
"access_token": "eyJ3ZWJtYXN0ZXJl…2VibWFzdGVydWlkIjoiMDY3MDY",
"expires_in": 3599,
"token_type": "Bearer"
}
Authorization Scopes
This document lists the OAuth 2.0 scopes that you might need to request to access Bing Webmaster APIs, depending on the level of access you need. Scopes also provide Bing Webmaster users using third-party apps the confidence that only the information they choose to share will be shared, and nothing more.
List of scopes:
Webmaster.read:
- Description: Read access to the user’s Bing webmaster tool data
- Visible to users: View the user’s Bing webmaster tool data
Webmaster.manage:
- Description: Read and write access to the user’s Bing webmaster tool data
- Visible to users: View and manage the user’s Bing webmaster tool data