🤯 Understanding Google OAuth2 Token Refresh in Node.js (with googleapis)

When integrating Google OAuth2 in your Node.js / Next.js app using the googleapis library, a key question is:

🧠 "How do I handle access token expiration and refresh automatically?"

Turns out — you don't need to handle much at all. But understanding why and how took me down a rabbit hole. Here's what I learned so you don't get stuck like I did.

🔑 The Basics

When you authorize a user via the OAuth2 web server flow (access_type: "offline"), Google returns:

• access_token – short-lived, used for API requests
• refresh_token – used to get a new access token
• expiry_date – timestamp (in ms) when the access token expires

✅ The Simple Solution

The good news? You can make Google auto-refresh tokens just by doing this:

oauth2Client.setCredentials({
  access_token,
  refresh_token,
  expiry_date,
});

Then, call the API like normal:

const calendar = google.calendar({ version: "v3", auth: oauth2Client });
await calendar.events.delete({
  calendarId: "primary",
  eventId: "123",
});

If the access_token is expired, the client automatically refreshes it using the refresh_token.

🎉 No need to manually check expiry or refresh!

🤔 Then Why Do People Use getAccessToken()?

Great question!

Use getAccessToken() only when you need the raw token string, such as:

• Adding it to custom headers
• Injecting into a GraphQL/WebSocket context
• Logging / debugging

const { token } = await oauth2Client.getAccessToken();

Otherwise, skip it. Google handles everything internally during requests.

🧪 How I Tested the Refresh Behavior

Want to test token refresh manually without waiting for expiration?

Just fake the expiry like this:

oauth2Client.setCredentials({
  access_token,
  refresh_token,
  expiry_date: Date.now() - 1000, // fake it as expired
});

Then make a normal API call — it will refresh in the background.

👀 Bonus: Log When Token Refresh Happens

You can log when a refresh happens using the tokens event:

oauth2Client.on("tokens", (tokens) => {
  console.log("🔄 Refreshed tokens:", tokens);
});

Perfect for debugging or confirming it's working.

🧠 Lessons Learned

• The docs are technically right, but don't show everything clearly
• The googleapis package uses google-auth-library internally, which handles refresh logic
• Set a past expiry_date + make a request = auto-refresh
• Use getAccessToken() only when you need the token string
• You don't need to memorize class hierarchies — but checking inheritance (like OAuth2Client → AuthClient) helps

🏁 Final Tip

If you're ever unsure about how a client like OAuth2Client behaves:

• Look for event hooks (like tokens)
• Check method docs (getAccessToken, request)
• Look at class inheritance
• Test locally with fake expiry