claude-code - 💡(How to fix) Fix [DOCS] Authentication docs missing recovery guidance for expired `CLAUDE_CODE_OAUTH_TOKEN` [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Credential management", "Authentication precedence", and "Generate a long-lived token"

Current Documentation

The docs currently say:

1. CLAUDE_CODE_OAUTH_TOKEN environment variable. A long-lived OAuth token generated by claude setup-token. Use this for CI pipelines and scripts where browser login isn't available.

The command walks you through OAuth authorization and prints a token to the terminal. It does not save the token anywhere; copy it and set it as the CLAUDE_CODE_OAUTH_TOKEN environment variable wherever you want to authenticate:

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.117 includes: "Fixed /login having no effect when launched with CLAUDE_CODE_OAUTH_TOKEN env var and that token expires".

That fix exposes a user-facing authentication path the docs do not currently explain: what should happen when Claude Code is launched with CLAUDE_CODE_OAUTH_TOKEN, that token later expires, and the user tries to recover interactively.

The current docs explain that CLAUDE_CODE_OAUTH_TOKEN is an alternative to /login and that expired OAuth sessions should be fixed with /login, but they do not connect those two cases. They do not say whether /login is expected to recover from an expired env-var token, whether users need to remove the environment variable first, or when they should use the refresh-token flow instead.

Suggested Improvement

Add a short subsection to the authentication or troubleshooting docs for expired env-var OAuth credentials, for example "When CLAUDE_CODE_OAUTH_TOKEN expires".

That section should clarify:

• the intended interaction between CLAUDE_CODE_OAUTH_TOKEN and /login / claude auth login
• the supported recovery path after an env-var OAuth token expires in an interactive session
• when to prefer CLAUDE_CODE_OAUTH_REFRESH_TOKEN plus CLAUDE_CODE_OAUTH_SCOPES for renewable automated authentication instead of a fixed access token
• how to verify which auth method is active with /status

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Source: Changelog v2.1.117

Exact changelog entry: Fixed /login having no effect when launched with CLAUDE_CODE_OAUTH_TOKEN env var and that token expires