Many provider APIs issue short-lived access tokens and longer-lived refresh tokens. When an access token expires, the integration exchanges the refresh token for a new token set. This flow introduces concurrency and recovery problems: multiple workers may refresh at once, refresh tokens may rotate, and a failed response may leave the application unsure which token is valid.
Store token state explicitly
Associate tokens with the provider account and granted scopes. Store expiry time, token type, last refresh time and provider identity. Protect refresh tokens at rest and restrict access to the process that needs them. Do not log token values or include them in exception messages.
Coordinate refresh operations
Before refreshing, check whether another worker has already updated the token. Use a short database lock or atomic version check so only one worker performs the refresh for a credential set. After receiving a new token response, persist the access token and rotated refresh token together. If the provider invalidates the old refresh token immediately, partial persistence can break the integration.
Handle ambiguous failures
A timeout during refresh does not necessarily mean the provider rejected the request. The provider may have rotated the refresh token while the response was lost. Follow the provider's recovery guidance; do not blindly retry an old refresh token indefinitely. Some providers offer grace periods or token-family recovery mechanisms.
Reauthorize when necessary
If refresh is revoked or consent is withdrawn, mark the connection as requiring user action. Stop retrying and provide a clear reconnection flow. Request only scopes the feature needs and explain why renewed consent is required.
Further reading
- RFC 6749: Refreshing an Access Token — https://www.rfc-editor.org/rfc/rfc6749
- OAuth 2.0 Security Best Current Practice — https://www.rfc-editor.org/rfc/rfc9700