[FEATURE] Auth fallback: use Claude.ai subscription first, fall back to API key on rate limit

[mengano-net]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Feature Request

Summary

Support a fallback authentication mode where Claude Code uses a Claude.ai
subscription (OAuth) as the primary auth, and automatically switches to an
API key when the subscription's usage limit is reached.

Motivation

Users who have both a Claude.ai Pro/Teams subscription and an Anthropic API
key currently have no way to:

1. Prioritize their subscription (avoiding unnecessary API charges)
2. Seamlessly continue working when the subscription rate limit is hit

Today, both auth methods conflict — Claude Code throws a warning and requires
choosing one. The manual workaround (/logout → switch → /logout → switch
back) is disruptive during active development sessions.

Proposed Behavior

Add a configuration option (e.g., in ~/.claude/settings.json) such as:

{
"authStrategy": "subscription-first",
"apiFallbackKey": "sk-ant-..."
}

When the claude.ai session hits a usage limit (HTTP 429 / rate limit response),
Claude Code automatically falls back to the API key and notifies the user.

Use Case

• Developer has Claude Pro (daily limit)
• Works normally via OAuth during the day
• Hits the usage cap mid-session
• Claude Code transparently switches to API key billing to continue
• Next day, subscription resets and OAuth resumes as primary

Current Behavior

Both auth methods cannot coexist. User must manually /logout and reconfigure
to switch between them.

Environment

• OS: macOS
• Claude Code version: (2.1.50)

Proposed Solution

Um ... Up to Anthropic, I've got nothing to add here

Alternative Solutions

No response

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

No response

Additional Context

No response

[github-actions]

Found 3 possible duplicate issues:

1. [FEATURE] Add automatic authentication failover between Pro Plan and API #8679
2. Feature Request: API Fallback for Pro/Max Subscriptions When Limits Are Reached #2944
3. Use subscription and fallback to credits, or allow switching without re-login #2271

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically closed as a duplicate of #8679.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.