Bug in Bing Webmaster Tools OAuth 2.0?

Question

Bug in Bing Webmaster Tools OAuth 2.0?

RA van Hagen 5

Hi, while creating a web app that uses the Bing Webmaster Tools API with OAuth 2.0 credentials, I ran into several issues.

The documentation on https://learn.microsoft.com/en-us/bingwebmaster/oauth2 seems to have some errors.
The common assumption (on these forums) that refresh tokens are one-time use seems not to be the case.
The app receives a new refresh token each time when refreshing an expired access token. But using this new refresh token (on the next access token expiration) will cause a invalid_grant error response. This seems to go against the OAuth 2 specs.

What I expected was this:

The app, after the first authorization request, obtains the first access and refresh tokens. By the time the access token expires (one hour, I noticed) the app uses the refresh token to request a new access token. And if a new refresh token is received with the request, the app replaces the old refresh token with the new one for future refresh requests.

But...

I found that the app was getting invalid_grant responses as soon as it uses the second refresh token. But if I make the app ignore these new refresh tokens, and keep using the original refresh token, it does obtain a new access token each time.

Or at least, today. No idea when the refresh token will expire...

Can anyone explain why Bing sends a new refresh token on each access token refresh? And why these new refresh tokens cause an invalid grant response?

Should the app save these refresh tokens for later use but only use them after the original one has expired or something? Feels messy...

RA van Hagen 5 Reputation points

2025-12-12T23:42:21.1466667+00:00

I should also note that on https://learn.microsoft.com/en-us/bingwebmaster/oauth2 I read: "refresh_token | A token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access." But seeing there are other inconsistencies on that page, I doubt the validity (of both the statement and the token).

2 answers

Your answer

RA van Hagen 5 Reputation points

2025-12-12T23:42:21.1466667+00:00

I should also note that on https://learn.microsoft.com/en-us/bingwebmaster/oauth2 I read: "refresh_token | A token that you can use to obtain a new access token. Refresh tokens are valid until the user revokes access." But seeing there are other inconsistencies on that page, I doubt the validity (of both the statement and the token).

Answer 1

It seems you are encountering issues with the refresh tokens in the Bing Webmaster Tools API's OAuth 2.0 implementation. Based on the context provided, here are some insights:

Refresh Token Behavior: According to the OAuth 2.0 specification, when a new refresh token is issued, the old refresh token should be discarded. This means that your application should replace the old refresh token with the new one each time it is received. However, if you are receiving an invalid_grant error when trying to use the new refresh token, it indicates that there may be an issue with how the refresh token is being handled or validated.
Invalid Grant Error: The invalid_grant error can occur for several reasons, including using a refresh token that has expired, been revoked, or is not valid for the requested scope. If the new refresh token is causing this error, it might be due to the token being invalidated by the authorization server for some reason, such as a change in user consent or other security measures.
Token Expiration: Refresh tokens are generally long-lived, but they can be invalidated at any moment. Therefore, your application should be designed to handle the possibility that a refresh token may no longer be valid when you attempt to use it.
Best Practices: It is advisable to always use the most recent refresh token received after a successful token refresh request. If you receive a new refresh token, you should store it and discard the old one. If you encounter an invalid_grant error, you may need to prompt the user to re-authenticate to obtain a new set of tokens.

In summary, while it may seem messy, the behavior you are observing aligns with the OAuth 2.0 specification regarding refresh tokens. It's important to handle token management carefully to ensure that your application can respond to changes in token validity appropriately.

References:

Answer 2

Aron 7,500 Independent Advisor

Hi there, thanks for sticking with me while we sort this out.

From what I’m seeing, the issue comes down to how Bing Webmaster Tools handles OAuth refresh tokens: they rotate on each successful refresh, and the previous token becomes invalid, so if the app reuses an old token or two refresh attempts happen close together, Bing returns invalid_grant.

To get this stable, let’s make sure we’re posting to https://www.bing.com/webmasters/oauth/token with grant_type=refresh_token, and after a successful refresh we immediately and atomically save the new refresh_token and use a single thread/locked path so only one refresh can run at a time.

Also, double‑check the redirect URI matches exactly, your system clock is accurate, and scopes are consistent; if a refresh still fails, kick off a full re‑auth to get a new code and token pair.

Quick fallback while we test: you can use the API Key from the Webmaster Tools “API Access” section to keep calls working.

A couple questions to help me pinpoint this: are multiple instances or jobs trying to refresh at the same time, how are you persisting and swapping the new refresh token, and can you share the exact form body (with secrets removed) you’re sending to the token endpoint?

Regards,
Aron

RA van Hagen 5 Reputation points

2025-12-13T00:07:06.4633333+00:00

The app stores the new refresh token in the exact same manner it stores the first refresh token. The original refresh token is accepted just fine but the new refresh token is always causing an invalid grant response, forcing the need to do a re-auth which then lasts 2 hours (two access tokens) before failing again.

I verified that there are no multiple instances doing requests simultaneously.

One question: is it normal that there is a new refresh token distributed on each access token refresh? I see it happen on forced refreshes that happen within a minute after the first auth. It feels to me like that is not supposed to happen... Sure at some point but not immediately.

Even weirder to me is the fact that the initial refresh token still works (in fact, is the only one that keeps working) after new refresh tokens have been received. Does not sound at all like compliant with OAuth specs to me.

I'll reply with the requests as they are made by the app in the next comment.

RA van Hagen 5

I should mention: this is a WordPress/PHP app. I use the following code to build the auth request, after receiving the auth code via the redirect URI.

$body = array(
	'code'          => $authorization_code,
	'client_id'     => $client_id,
	'client_secret' => $client_secret,
	'redirect_uri'  => site_url( 'index.php?bing_oauth' ),
	'grant_type'    => 'authorization_code',
);
$response = wp_remote_post(
	'https://www.bing.com/webmasters/oauth/token',
	array(
		'body'    => $body,
		'headers' => array(
			'Content-Type' => 'application/x-www-form-urlencoded',
		),
	)
);

Which, I assume, sends the following post request to https://www.bing.com/webmasters/oauth/token

Content-Type: application/x-www-form-urlencoded

code=xxxx
&client_id=xxxx
&client_secret=xxxx
&redirect_uri=https%3A%2F%2Fexample.com%2Findex.php?bing_oauth
&grant_type=authorization_code

I assume this, because the response is as expected:

Array
(
    [access_token] => xxxx
    [token_type] => bearer
    [expires_in] => 3599
    [refresh_token] => xxxx
)

The app then stores these tokens separately in the database and plans a refresh for the next hour.

I'll continue with the refresh request anatomy in the next comment.

RA van Hagen 5 Reputation points

2025-12-13T01:08:18.4366667+00:00
Here is the code that builds the refresh request:

$body = array( 'grant_type' => 'refresh_token', 'refresh_token' => $refresh_token, 'client_id' => $client_id, 'client_secret' => $client_secret, ); $response = wp_remote_post( 'https://www.bing.com/webmasters/oauth/token' array( 'body' => $body, 'headers' => array( 'Content-Type' => 'application/x-www-form-urlencoded', ), 'timeout' => 15, ) );

Which, I assume again, sends the following post request to https://www.bing.com/webmasters/oauth/token

Content-Type: application/x-www-form-urlencoded grant_type= refresh_token &refresh_token=xxxx &client_id=xxxx &client_secret=xxxx

This returns on the first refresh, the expected result:

Array ( [access_token] => yyyy [token_type] => bearer [expires_in] => 3599 [refresh_token] => yyyy )

Using this new access token works fine. But... using this new refresh token to run through the same refresh request routine, always fails with an invalid grant response.

But if I force the app to ignore the new refresh token yyyy and use the original xxxx one, it does work fine. New access token and refresh token are received.

The third access token works fine too, until expiration ofcourse. As long as I keep re-using the original refresh token because any new refresh token will fail.
RA van Hagen 5 Reputation points

2025-12-13T01:12:14.61+00:00

Thank you Aron, for taking the time to look into this with me :)
RA van Hagen 5 Reputation points

2025-12-13T13:40:33.1466667+00:00
The thing is, the app applies the exact same routines to access Google OAuth. And when it refreshes an access token there, it mostly gets a response like this:

Array ( [access_token] => zzzz [expires_in] => 3599 [scope] => https://www.googleapis.com/auth/webmasters [token_type] => Bearer )

Notice there is no new refresh token there. But if there is one, the app saves that new one and discards the old refresh token.

This works fine and has been stable for a few weeks now.

While Bing on the other hand sends a new refresh token along with each access token refresh. And then refuses this new refresh token with an invalid grant response on subsequent access token refresh requests.

Also notice that there is no scope in the Bing response...

I am so confused :/

Share via

Bug in Bing Webmaster Tools OAuth 2.0?

2 answers

Your answer