Sample code for 30+ languages & platforms
Ruby Requires Chilkat v11.0.0+

Gmail SMTP, IMAP, and POP3: Refresh an OAuth2 Token

See more OAuth2 Examples

Refresh a Gmail access token without opening a browser. Use the same OAuth client and the offline refresh token saved during initial authorization. A refreshed token can authenticate SMTP, IMAP, or POP3 for the authorized mailbox.

Google normally does not return another refresh token. The example retains the saved refresh token when omitted, accepts a replacement when provided, preserves the granted scope when omitted, and records the new access token's issue time and lifetime. A failed exchange leaves the old cache untouched. File writes are checked; production applications should use protected storage and serialize/atomically commit updates.

Access tokens normally last about an hour. Refresh ahead of expiry and reconnect long-lived protocol sessions when necessary. Refresh does not add scopes or restore a revoked grant. An invalid_grant response can require fresh user authorization; do not retry it indefinitely. External apps in Testing normally receive seven-day refresh tokens for this scope.

Gmail SMTP, IMAP, and POP3 use the https://mail.google.com/ OAuth scope. Narrower Gmail REST scopes such as gmail.send or gmail.readonly do not authorize these protocols. Public applications using this restricted scope must meet Google's verification requirements. See Gmail OAuth scopes and XOAUTH2.

Google documentation

Chilkat Ruby Downloads

Ruby
require 'chilkat'

success = false

#  Assumes Chilkat is unlocked. See Global Unlock Sample.

token = Chilkat::CkJsonObject.new()
success = token.LoadFile("gmail-mail-token.json")
if (success != true)
    print "Could not read gmail-mail-token.json from the private working directory." + "\n";
    exit
end

if ((token.JsonTypeOf("refresh_token") != 1) or (token.StringOfEquals("refresh_token","",true) == true))
    print "Authorize the account for offline access first." + "\n";
    exit
end

oauth = Chilkat::CkOAuth2.new()
oauth.put_TokenEndpoint("https://oauth2.googleapis.com/token")
oauth.put_ClientId("YOUR_DESKTOP_CLIENT_ID")
oauth.put_ClientSecret("YOUR_DESKTOP_CLIENT_SECRET")
oauth.put_RefreshToken(token.stringOf("refresh_token"))
success = oauth.RefreshAccessToken()
if (success != true)
    print "Refresh failed. Check the OAuth client and grant. A revoked or expired grant requires fresh consent." + "\n";
    exit
end

fresh = Chilkat::CkJsonObject.new()
success = fresh.Load(oauth.accessTokenResponse())
if (success != true)
    print "Could not parse the refresh response." + "\n";
    exit
end

if ((fresh.JsonTypeOf("access_token") != 1) or (fresh.StringOfEquals("access_token","",true) == true))
    print "The refresh response did not contain an access token." + "\n";
    exit
end

if ((fresh.JsonTypeOf("refresh_token") != 1) or (fresh.StringOfEquals("refresh_token","",true) == true))
    fresh.UpdateString("refresh_token",token.stringOf("refresh_token"))
end

if ((fresh.HasMember("scope") != true) and (token.JsonTypeOf("scope") == 1))
    fresh.UpdateString("scope",token.stringOf("scope"))
end

#  Google normally omits refresh_token on refresh. Keep the previous one in that case.
#  Use the new expires_in, not the old response's expiration information.
obtained = Chilkat::CkDateTime.new()
obtained.SetFromCurrentSystemTime()
fresh.UpdateString("obtained_at",obtained.getAsTimestamp(false))
success = fresh.WriteFile("gmail-mail-token.json")
if (success != true)
    print "Could not save the refreshed credentials." + "\n";
    exit
end

print "Refreshed the access token." + "\n";