Skip to main content

​
Overview

The CLI Proxy API supports OAuth authentication for various AI providers. OAuth credentials are stored in the auth-dir directory and managed through the Management API or CLI.

​
Supported OAuth Providers

The following providers support OAuth authentication:
  • Gemini CLI (gemini-cli) - Google Gemini via CLI authentication
  • Vertex AI (vertex) - Google Vertex AI with service accounts
  • AI Studio (aistudio) - Google AI Studio
  • Antigravity (antigravity) - Gemini 3.0 experimental access
  • Claude (claude) - Anthropic Claude via OAuth
  • Codex (codex) - OpenAI Codex
  • Qwen (qwen) - Alibaba Qwen models
  • iFlow (iflow) - iFlow AI
  • Kimi (kimi) - Moonshot AI Kimi

​
OAuth Model Aliases

Global OAuth model name aliases allow you to rename model IDs for both model listing and request routing.
​
oauth-model-alias
object
Per-channel model name aliases. Each channel can have multiple aliases defined.
Aliases do not apply to API key-based providers (gemini-api-key, codex-api-key, claude-api-key, openai-compatibility, vertex-api-key, ampcode). Those providers have their own per-credential alias systems.

​
Alias Configuration

Each alias entry has three properties:
​
oauth-model-alias.<channel>[].name
string
required
Original model name under this channel.
​
oauth-model-alias.<channel>[].alias
string
required
Client-visible alias for the model.
​
oauth-model-alias.<channel>[].fork
boolean
default:"false"
When true, keep the original model name and add the alias as an extra model. When false, replace the original name with the alias.

​
OAuth Alias Example

oauth-model-alias:
  gemini-cli:
    - name: "gemini-2.5-pro"
      alias: "g2.5p"
      fork: false  # Replaces "gemini-2.5-pro" with "g2.5p"
    - name: "gemini-2.5-flash"
      alias: "flash"
      fork: true   # Keeps both "gemini-2.5-flash" and "flash"
  
  vertex:
    - name: "gemini-2.5-pro"
      alias: "g2.5p"
  
  aistudio:
    - name: "gemini-2.5-pro"
      alias: "g2.5p"
  
  antigravity:
    - name: "gemini-3-pro-high"
      alias: "gemini-3-pro-preview"
  
  claude:
    - name: "claude-sonnet-4-5-20250929"
      alias: "cs4.5"
    - name: "claude-opus-4-5-20251101"
      alias: "opus-latest"
  
  codex:
    - name: "gpt-5"
      alias: "g5"
  
  qwen:
    - name: "qwen3-coder-plus"
      alias: "qwen-plus"
  
  iflow:
    - name: "glm-4.7"
      alias: "glm-god"
  
  kimi:
    - name: "kimi-k2.5"
      alias: "k2.5"
When to use fork: true:Use fork: true when you want both the original model name and the alias available to clients. This is useful for:
  • Gradual migration from old to new names
  • Providing both short and full model names
  • Supporting multiple naming conventions simultaneously

​
OAuth Excluded Models

Exclude specific models from OAuth providers using patterns.
​
oauth-excluded-models
object
Per-provider model exclusion lists. Each provider can have multiple exclusion patterns.

​
Exclusion Patterns

Supports four pattern types:
  1. Exact match: "gemini-2.5-pro" - Excludes only this exact model
  2. Prefix wildcard: "gemini-2.5-*" - Excludes gemini-2.5-flash, gemini-2.5-pro, etc.
  3. Suffix wildcard: "*-preview" - Excludes gemini-3-pro-preview, claude-opus-preview, etc.
  4. Substring wildcard: "*flash*" - Excludes gemini-2.5-flash-lite, flash-pro, etc.

​
Exclusion Example

oauth-excluded-models:
  gemini-cli:
    - "gemini-2.5-pro"     # Exclude specific model
    - "gemini-2.5-*"       # Exclude all 2.5 models
    - "*-preview"          # Exclude all preview models
    - "*flash*"            # Exclude all flash variants
  
  vertex:
    - "gemini-3-pro-preview"
  
  aistudio:
    - "gemini-3-pro-preview"
  
  antigravity:
    - "gemini-3-pro-preview"
  
  claude:
    - "claude-3-5-haiku-20241022"
    - "*-thinking"         # Exclude thinking models
  
  codex:
    - "gpt-5-codex-mini"
    - "*-mini"             # Exclude all mini models
  
  qwen:
    - "vision-model"
  
  iflow:
    - "tstars2.0"
  
  kimi:
    - "kimi-k2-thinking"
    - "*-thinking"         # Exclude all thinking variants
Wildcard patterns are case-insensitive and match against lowercase model names.

​
OAuth Setup

​
1. Configure Authentication Directory

auth-dir: "~/.cli-proxy-api"

​
2. Enable Management API

remote-management:
  allow-remote: false
  secret-key: "your-management-password"

​
3. Initiate OAuth Flow

Use the Management API to start OAuth authentication: 
curl -X POST https://localhost:8317/v0/management/oauth/gemini-cli \
  -H "X-Management-Key: your-management-password"
Response: 
{
  "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
  "state": "random-state-token"
}

​
4. Complete Authorization

Open the auth_url in a browser, authorize the application, and copy the callback URL.

​
5. Exchange Code for Token

curl -X POST https://localhost:8317/v0/management/oauth/gemini-cli/callback \
  -H "X-Management-Key: your-management-password" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "authorization-code-from-callback",
    "state": "random-state-token"
  }'

​
6. Verify Session

curl https://localhost:8317/v0/management/sessions \
  -H "X-Management-Key: your-management-password"

​
Complete OAuth Configuration Example

# Authentication Directory
auth-dir: "~/.cli-proxy-api"

# Management API (required for OAuth)
remote-management:
  allow-remote: false
  secret-key: "management-password-here"

# OAuth Model Aliases
oauth-model-alias:
  gemini-cli:
    - name: "gemini-2.5-pro"
      alias: "g2.5p"
    - name: "gemini-2.5-flash"
      alias: "flash"
      fork: true
  claude:
    - name: "claude-sonnet-4-5-20250929"
      alias: "sonnet-latest"
  codex:
    - name: "gpt-5"
      alias: "gpt-latest"

# OAuth Excluded Models
oauth-excluded-models:
  gemini-cli:
    - "*-preview"          # Exclude preview models
    - "gemini-1.*"         # Exclude v1 models
  claude:
    - "claude-3-*"         # Only use Claude 4+ models
  codex:
    - "*-mini"             # Exclude mini variants

​
Provider-Specific Notes

​
Gemini CLI

oauth-model-alias:
  gemini-cli:
    - name: "gemini-2.5-pro"
      alias: "pro"
Requires Google Cloud authentication via gcloud CLI or service account.

​
Claude OAuth

oauth-model-alias:
  claude:
    - name: "claude-sonnet-4-5-20250929"
      alias: "sonnet"
Requires Anthropic account with OAuth enabled.

​
Vertex AI

oauth-model-alias:
  vertex:
    - name: "gemini-2.5-pro"
      alias: "vertex-pro"
Requires Google Cloud service account with Vertex AI permissions.

​
Best Practices

Alias Naming:
  • Use short, memorable aliases (e.g., "g2.5p" instead of "gemini-2.5-pro")
  • Maintain consistency across providers
  • Document custom aliases for your team
Security:
  • Keep auth-dir permissions restricted (0700)
  • Rotate OAuth tokens periodically
  • Monitor OAuth session access logs
  • Use allow-remote: false for Management API
Exclusion vs Aliases:Exclusions are applied before aliases. If you exclude a model, you cannot create an alias for it.

​
Troubleshooting

​
OAuth Flow Fails

  1. Check Management API is enabled (secret-key is set)
  2. Verify auth-dir exists and is writable
  3. Ensure OAuth provider supports your account type

​
Models Not Appearing

  1. Check oauth-excluded-models for matching patterns
  2. Verify OAuth session is active (GET /v0/management/sessions)
  3. Ensure provider supports the requested models

​
Aliases Not Working

  1. Verify channel name matches provider exactly (case-sensitive)
  2. Check for typos in name field (must match upstream model name)
  3. Ensure fork: false if you want to replace (not add to) model name

Build docs developers (and LLMs) love

Get started for freeTalk to us