gmail api - Using Refresh Token Exception { "error" : "invalid_grant" }'

Question

I've successfully built an application that fetches an access and refresh token.

In my script I check if the access token is valid and if not I then use the refresh token to gain access $client->refreshToken($refreshToken);

Code in full,

    $refreshToken = '<REFRESH_TOKEN>';

    $client_id = '<CLIENT_ID>';
    $client_secret = '<CLIENT_SECRET>';

    // Setup infomation
    $client = new Google_Client();
    $client->setClientId($client_id);
    $client->setClientSecret($client_secret);
    $client->setAccessType("offline");
    $client->addScope("https://mail.google.com/");

    // If access token is not valid use refresh token
    if($client->isAccessTokenExpired()) {

        // Use refresh token
        $client->refreshToken($refreshToken);

    } else {

        // Use access token
        echo $client->setAccessToken($accessToken);

    }

However when trying to use the refresh token I get an excpetion :

Fatal error: Uncaught exception 'Google_Auth_Exception' with message 'Error refreshing the OAuth2 token, message: '{ "error" : "invalid_grant" }''

Answer 1

In the OAuth2 spec, "invalid_grant" is sort of a catch-all for all errors related to invalid/expired/revoked tokens (auth grant or refresh token).

There's a lot potential causes for the problems, here's a checklist:

1. Server clock/time is out of sync
2. Not authorized for offline access
3. Throttled by Google
4. Using expired refresh tokens
5. User has been inactive for 6 months
6. Use service worker email instead of client ID
7. Too many access tokens in short time
8. Client SDK might be outdated
9. Incorrect/incomplete refresh token
10. User has actively revoked access to our app
11. User has reset/recovered their Google password

I've written a short article summarizing each item with some debugging guidance to help find the culprit. We spent days hunting this down, hope it may help others turn those days into hours.