[FEATURE] Auth fallback: use Claude.ai subscription first, fall back to API key on rate limit
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] 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:
- Prioritize their subscription (avoiding unnecessary API charges)
- 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_
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗