OAuth 2.0 Token Refresh: Automatic Module Handling vs Manual Error Interception

When implementing secure service-to-service communication in Ballerina, managing the lifecycle of access tokens is critical for maintaining least-privilege access without causing service downtime.

The Constraint

The ballerina/auth/oauth2 module provides mechanisms for token management, but a design trade-off exists when handling expired credentials for user-presented tokens. While the module can automate refreshes for certain grant types, it typically returns a 401 Unauthorized response when a token expires during a request, shifting the burden of recovery to the service logic.

Technical Uncertainty

Developers must choose between relying on the module's internal refresh logic—which may not apply to all credential flows—or implementing a manual interception layer to catch 401 errors and trigger a refresh flow. This decision impacts the complexity of the error-handling middleware and the consistency of the authentication state.

• Does the oauth2 module support a configurable automatic refresh trigger for all grant types upon receiving a 401 response?
• What is the recommended pattern for implementing a manual refresh loop that maintains the least-privilege scope without re-authenticating the entire session?