Clarify intended procedure for detecting when a new access token has been generated and how/whether to store it #3568

Please make sure you have searched for information in the following guides.

• Search the issues already opened: https://github.com/GoogleCloudPlatform/google-cloud-node/issues
• Check our Troubleshooting guide: https://googlecloudplatform.github.io/google-cloud-node/#/docs/guides/troubleshooting
• Check our FAQ: https://googlecloudplatform.github.io/google-cloud-node/#/docs/guides/faq
• Check our libraries HOW-TO: https://github.com/googleapis/gax-nodejs/blob/main/client-libraries.md
• Check out our authentication guide: https://github.com/googleapis/google-auth-library-nodejs
• Check out handwritten samples for many of our APIs: https://github.com/GoogleCloudPlatform/nodejs-docs-samples

Documentation Request

When an access token is expired, performing an API request will automatically use the refresh token to fetch a new access token. However, this does not trigger the on('tokens) event; this only fires on the first authentication.

What is not explained clearly in the docs then, is how the new access token is meant to be detected so that it can be stored and reused for its validity period. Otherwise the new access token may be lost and users hit 401 Invalid Credentials errors in subsequent requests.

Is the intent that after each API call, we manually check the oAuth2Client for a new access token via oAuth2Client.credentials.access_token? I.e., add manual token checking logic after each API call? If this is the case, can explicit instructions be added that something like this is the intended approach?

Or is there some other event similar to tokens we can listen for on the oAuth2Client that will automatically trigger upon receiving an updated access token? (If not, can that feature be added?)

Perhaps the access token is not meant to be stored at all? Discarded after each request? But then we are fetching new access tokens for every request after the first hour.