Authentication Overview
CLI Proxy API supports multiple authentication methods to access AI providers:- OAuth 2.0 - Use your existing subscriptions (Gemini, Claude, Codex, etc.)
- API Keys - Traditional API key authentication (Gemini, Claude, OpenAI-compatible)
- Service Accounts - Google Cloud service accounts (Vertex AI)
Client Authentication
Clients authenticate to CLI Proxy API using API keys configured inconfig.yaml:
config.yaml
Authorization header:
OAuth Authentication
OAuth providers require interactive authentication through a web browser.OAuth Flow
PKCE (Proof Key for Code Exchange)
CLI Proxy API uses PKCE for enhanced OAuth security:- Generating a random
code_verifier - Creating a SHA256 hash as
code_challenge - Sending challenge in auth request
- Sending verifier in token exchange
Provider-Specific OAuth
Gemini CLI OAuth
- Standard OAuth 2.0 flow
- Refresh tokens for automatic renewal
- Multi-account support via separate auth files
Claude Code OAuth
- PKCE for security
- Organization UUID and account email in token response
- Custom TLS fingerprinting to bypass Cloudflare
OpenAI Codex OAuth
- JWT-based session tokens
- Organization membership tracking
- Refresh token rotation
Other OAuth Providers
Qwen Code:Token Storage
Authentication tokens are stored in the auth directory (~/.cli-proxy-api by default):
Token File Format
Each provider has a specific token structure:File Watching
CLI Proxy API watches the auth directory for changes usingfsnotify:
- Add new file → Credential becomes available immediately
- Modify file → Token updates applied automatically
- Delete file → Credential removed from rotation
Token Refresh
Theauth.Manager automatically refreshes tokens before they expire:
sdk/cliproxy/auth/conductor.go
- Background checks every 5 seconds
- Proactive refresh before expiry (varies by provider)
- Concurrent refresh up to 16 tokens at once
- Failure backoff 5 minutes on error
- Pending backoff 1 minute if already refreshing
Multi-Account Authentication
CLI Proxy API supports multiple accounts per provider:Adding Multiple Accounts
Account Selection
The routing strategy determines which account is used: Round-robin (default):config.yaml
config.yaml
Account Prefixes
You can target specific accounts using prefixes:config.yaml
API Key Authentication
Providers that support API keys can be configured directly:Gemini API Keys
config.yaml
Claude API Keys
config.yaml
OpenAI-Compatible Providers
config.yaml
Authentication Attributes
You can add metadata to credentials:~/.cli-proxy-api/[email protected]
- priority: Higher priority credentials selected first (default: 0)
- websockets: Enable WebSocket API access (default: false)
- description: Human-readable label (not used by system)
Quota & Cooldown
When a credential hits quota limits:- Error detected (HTTP 429 or quota exceeded message)
- Credential enters cooldown state
- Request automatically retries with next credential
- After cooldown period, credential returns to rotation
sdk/cliproxy/auth/conductor.go
config.yaml
Security Considerations
Token Storage
- Tokens stored in plaintext files
- Use file permissions to restrict access:
chmod 600 ~/.cli-proxy-api/* - Consider encrypting the auth directory at rest
API Keys
- Use environment variables:
CLI_PROXY_API_KEY=sk-your-key - Rotate keys regularly
- Use different keys for different clients/teams
Management API
config.yaml
Next Steps
OAuth Setup
Set up OAuth for each provider
API Keys
Configure API key providers
Multi-Account
Manage multiple accounts
Routing
Learn about credential selection