Hi Nick,

Thanks for reporting this, I'll ask around.

Hi Nick,

We indeed need to fix the documentation for a bit more clarity.

The behavior you described is by design.

The use case that it is trying to cover is to avoid a race condition when refreshing tokens on a multiple threads situation.

Imagine you have a web app, being used simultaneously by hundreds of users.

There is the chance that when a token needs to be refreshed, the refresh end point could be called multiple times, with the same refresh token, by the multiple threads.

Assuming the web app would persist the new refresh token for each thread, it would run the risk of doing so for a refresh token that in the mean time would be invalidated by the other threads.

So, while the access token received from the refresh end point is valid, calling the refresh end point with the old refresh token will return the same pair of tokens.

If you continue to do this after the new access token expires, then you will get an invalid refresh token error, which means that by this time (60 minutes after the initial refresh) you should have persisted the new refresh token and used it to get a new pair.

You can see this in action looking at the expires_in, every time you call the refresh the expires in decreases.

{
    "access_token": "nxxxK",
    "expires_in": 3733,
    "restricted_to": [],
    "refresh_token": "KxxxKpq",
    "token_type": "bearer"
}

Some time after:

{
    "access_token": "nxxxK",
    "expires_in": 3056,
    "restricted_to": [],
    "refresh_token": "KxxKpq",
    "token_type": "bearer"
}