feat: OAuth Marathon - multi-account credential rotation #8591
Description
OAuth Marathon 🏃
Keep running when you hit the wall. Automatic credential rotation for OAuth providers - when one account hits rate limits or auth errors, opencode seamlessly switches to your next available credential within the same provider.
Note: This rotates between multiple accounts within the same provider (e.g., two OpenAI logins), not between different providers.
Works for all OAuth providers — both core providers and plugins.
For plugin authors: Plugins that manage their own multi-account pools internally must register each account via
Auth.addOAuth()to benefit from this feature.
The Problem
Using OAuth providers with personal subscriptions often means hitting rate limits mid-session. Currently, when this happens, your request fails and you're stuck waiting.
Proposed Solution
Register multiple OAuth accounts for the same provider, and opencode will automatically:
- Rotate on 429 - Rate limited? Next credential steps in
- Retry on 401/403 - Force token refresh, failover if still failing
- Recover from network errors - Transient failures don't stop the run
- Track health - Cooldown periods prevent hammering exhausted credentials
- All exhausted - Returns the last error response gracefully
How to Add Multiple Accounts
Run opencode auth login multiple times for the same provider:
opencode auth login # Login with first account
opencode auth login # Login with second account (adds, doesn't replace)Architecture Overview
flowchart TD
A[Provider.getSDK] --> B[createOAuthRotatingFetch]
B --> C{fetchFn}
C -->|429 Rate Limit| D[moveToBack + notifyFailover]
C -->|401/403 Auth| E[markAccessExpired + retry]
C -->|Network Error| F[recordOutcome + notifyFailover]
C -->|200 OK| G[recordOutcome success]
D --> H[Try Next Credential]
E -->|Still fails| H
F --> H
H --> C
Use Cases
- Multiple OAuth subscription accounts for the same provider
- Resilience against transient auth failures and rate limits
Configuration (Optional)
Per-provider settings in opencode.json. Sensible defaults are used if omitted:
{
"provider": {
"openai": {
"oauth": {
"maxAttempts": 3, // default: number of accounts
"rateLimitCooldownMs": 60000, // default: 30000
"authFailureCooldownMs": 300000, // default: 300000
"toastDurationMs": 5000 // default: 8000
}
}
}
}Demo
OpenAI Account 1 → 429 Rate Limited
↓ (automatic)
OpenAI Account 2 → 200 OK ✅
↓
Toast: "Rate limited on openai. Switching OAuth credential..."