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

Resolved 💬 3 comments Opened Feb 23, 2026 by mengano-net Closed Feb 27, 2026

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:

  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_

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗