[DOCS] Authentication docs omit OAuth refresh behavior when the server revokes a token early

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/authentication

Section/Topic

Credential management and OAuth token handling for Claude.ai authentication

Current Documentation

The docs currently describe refresh behavior for apiKeyHelper, but not for Claude.ai OAuth tokens:

* Refresh intervals: by default, apiKeyHelper is called after 5 minutes or on HTTP 401 response. Set CLAUDE_CODE_API_KEY_HELPER_TTL_MS environment variable for custom refresh intervals. 5. CLAUDE_CODE_OAUTH_TOKEN environment variable. A long-lived OAuth token generated by [claude setup-token](#generate-a-long-lived-token). Use this for CI pipelines and scripts where browser login isn't available.

The troubleshooting page also only tells users to log in again if a token appears expired:

If Claude Code prompts you to log in again after a session, your OAuth token may have expired. Run /login to re-authenticate. If this happens frequently, check that your system clock is accurate, as token validation depends on correct timestamps.

What's Wrong or Missing?

Changelog v2.1.118 fixed OAuth token refresh failing when the server revokes a token before its local expiry time.

The docs do not explain that Claude Code's OAuth handling should treat the server as authoritative for token expiry/revocation and attempt refresh when the server rejects a token early. That leaves a gap for users troubleshooting unexpected auth failures, repeated login prompts, or automated environments using OAuth-based credentials.

Suggested Improvement

Add a short OAuth token lifecycle/troubleshooting subsection to authentication that explains:

• Claude Code can refresh OAuth-backed authentication when the server reports the token is expired or revoked, even if the local expiry timestamp has not elapsed yet.
• Server-side revocation, clock skew, or stale cached credentials can cause a token to fail before the locally stored expiry time.
• If refresh cannot recover the session, users should re-run /login or reprovision their OAuth credentials.

Also add a cross-reference from troubleshooting back to this explanation so "token expired" guidance distinguishes between recoverable refresh scenarios and cases that truly require manual re-authentication.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/authentication | Describes OAuth token types and credential precedence, but not server-authoritative refresh/revocation behavior |
| https://code.claude.com/docs/en/troubleshooting | Expired-token guidance currently jumps straight to /login and clock checks |
| https://code.claude.com/docs/en/env-vars | Documents CLAUDE_CODE_OAUTH_REFRESH_TOKEN, CLAUDE_CODE_OAUTH_SCOPES, and CLAUDE_CODE_OAUTH_TOKEN without explaining the refresh lifecycle |
| https://code.claude.com/docs/en/cli-reference | Documents claude setup-token, which links to the authentication flow affected by this gap |

Total scope: 4 pages affected

Source: Changelog v2.1.118

Exact changelog entry:

Fixed OAuth token refresh failing when the server revokes a token before its local expiry time