Google refresh tokens are used to generate an access token, even when the user is not available at the browser (the user is "offline"). Web applications typically save the refresh token of the user when he authorizes the Google application. The application can later use this refresh token to generate an access token, and make API calls on behalf of the user directly from the server.
The most popular use of a refresh token is during the execution of a cron job at the server. For example, a cron script would use the refresh token to generate a Google Analytics report for the user at a specific time.
Typically developers have some questions over the usage of Google refresh tokens. This article contains some of the common questions asked.
I got a refresh token previously, but now Google stopped sending refresh token
For the first time when the user authorizes your application he will see a consent screen. Through the consent screen he allows the application to get access to his data via API calls. Typically after the first time, user will not see a consent screen.
It is through this consent screen, you get a refresh token. No consent screen means no refresh token.
To force the application to show a consent screen, set prompt=consent in the Google OAuth url. This will ensure that Google returns a refresh token.
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
scope=API_SCOPE&
redirect_uri=REDIRECT_URL&
response_type=code&
access_type=offline&
prompt=consent
I got a new refresh token. Does it mean that my older refresh token will not work ?
The older refresh token will work too. However Google imposes a limit of 50 refresh tokens per user for each application. If this limit is reached, creating a new token automatically will invalidate the oldest token without warning.
This means that for the first 50 times, you will get a new refresh token, and all the 50 refresh tokens will work.
However when the 51st refresh token comes, the first refresh token becomes invalidated. The 52nd refresh token will invalidate the 2nd refresh token. And so on.
Also the limit of 50 is not a fixed one. For Google Analytics API is is set to 25. The exact limit can be found in the documentation of the API. The documentation of each Google API typically has a section "Authorization". In this section, you can find the exact limit. If the limit is not listed, it is safe to consider it as 50.
In general it is not a good idea to request a refresh token each time when the user logs in. A refresh token is returned each time when the Google OAuth url contains the parameter prompt=consent. Setting prompt=none would not return a refresh token.
In the worst case, when your application is forced to get a new refresh token each time, make sure that your application is saving the latest refresh token, and removing the older refresh token.
When does a refresh token expire ?
Refresh tokens do not expire, unless there are few special conditions :
- The user has removed your Google application.
- The refresh token has not been used for six months.
- The user changed password and the refresh token contained Gmail scopes.
This means that the refresh token will be invalidated only when he had previously given the permisions for managing his Gmail, and then later changed his password.
For the rest of Google services like Youtube, Calendar etc, a changed password will not invalidate the refresh token. - The application generated a new refresh token for the user for more than 50 times.
See the above question I got a new refresh token. Does it mean that my older refresh token will not work for more information.
Is it a good idea to get a new refresh token from the user every time he logs-in to my Google application ?
No. As discussed above there is a limit of 50 refresh tokens for each user. This does not mean that Google will not return a refresh token after the 50th API call. A refresh token will be returned, but the older refresh token will be invalidated. See the question I got a new refresh token. Does it mean that my older refresh token will not work for more information on this.