Skip to main content

​
Overview

The CLI Proxy API supports multiple authentication methods depending on which endpoints you’re accessing:
  1. API Key Authentication - For main API endpoints (/v1/*, /v1beta/*)
  2. Management Secret - For management endpoints (/v0/management/*)
  3. WebSocket Authentication - Optional authentication for WebSocket connections
  4. Local Password - For localhost-only management access (TUI mode)

​
API Key Authentication

​
Configuration

API keys are configured in your config.yaml file:
config.yaml
api-keys:
  - "your-api-key-1"
  - "your-api-key-2"
  - "your-api-key-3"

​
Using API Keys

Include your API key in the Authorization header as a Bearer token:
cURL Example
curl https://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-1" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
Python Example
import openai

client = openai.OpenAI(
    base_url="http://localhost:8317/v1",
    api_key="your-api-key-1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "Hello!"}]
)
JavaScript Example
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:8317/v1',
  apiKey: 'your-api-key-1'
});

const response = await client.chat.completions.create({
  model: 'gemini-2.5-flash',
  messages: [{ role: 'user', content: 'Hello!' }]
});

​
No Authentication Mode

When no API keys are configured in config.yaml, the API allows all requests without authentication:
config.yaml
# Empty or no api-keys section = no authentication required
api-keys: []
This mode should only be used in development or when the API is behind a secure gateway.

​
Management API Authentication

Management endpoints require a secret key for authentication.

​
Configuration

Set the management secret key in config.yaml:
config.yaml
remote-management:
  # Management key - required for ALL management endpoints
  secret-key: "your-secure-management-key"
  
  # Whether to allow remote (non-localhost) access
  allow-remote: false
If secret-key is empty, all /v0/management/* endpoints return 404 Not Found.

​
Environment Variable

You can also set the management password via environment variable: 
export MANAGEMENT_PASSWORD="your-secure-management-key"
The environment variable takes precedence over the config file.

​
Using Management Authentication

Include the secret key in the Authorization header:
Management API Request
curl http://localhost:8317/v0/management/config \
  -H "Authorization: Bearer your-secure-management-key"
Get Usage Statistics
curl http://localhost:8317/v0/management/usage \
  -H "Authorization: Bearer your-secure-management-key"
Update Configuration
curl -X PUT http://localhost:8317/v0/management/config.yaml \
  -H "Authorization: Bearer your-secure-management-key" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @config.yaml

​
Localhost-Only Access

By default, management endpoints are restricted to localhost:
config.yaml
remote-management:
  allow-remote: false  # Only localhost can access (default)
To allow remote access:
config.yaml
remote-management:
  allow-remote: true  # Allow remote management access
Enabling remote management access exposes sensitive configuration endpoints to the network. Ensure you use a strong secret key and proper network security.

​
WebSocket Authentication

WebSocket connections can optionally require authentication.

​
Configuration

config.yaml
# Enable authentication for WebSocket endpoints
ws-auth: true
When ws-auth: true, WebSocket connections must include the API key in the request.

​
WebSocket Authentication Example

WebSocket with Auth
const ws = new WebSocket('ws://localhost:8317/v1/responses', {
  headers: {
    'Authorization': 'Bearer your-api-key-1'
  }
});
For the OpenAI Responses WebSocket endpoint:
cURL WebSocket Upgrade
curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Authorization: Bearer your-api-key-1" \
  http://localhost:8317/v1/responses

​
Provider-Specific API Keys

In addition to client authentication, you can configure upstream provider API keys:

​
Gemini API Keys

config.yaml
gemini-api-key:
  - api-key: "AIzaSy...01"
    prefix: "team-a"  # Optional: require "team-a/model-name"
    base-url: "https://generativelanguage.googleapis.com"

​
Claude API Keys

config.yaml
claude-api-key:
  - api-key: "sk-ant-..."
    prefix: "production"
    base-url: "https://api.anthropic.com"

​
Codex API Keys

config.yaml
codex-api-key:
  - api-key: "sk-..."
    prefix: "dev"

​
OpenAI-Compatible Providers

config.yaml
openai-compatibility:
  - name: "openrouter"
    prefix: "or"
    base-url: "https://openrouter.ai/api/v1"
    api-key-entries:
      - api-key: "sk-or-v1-..."

​
OAuth Authentication

The API supports OAuth flows for various providers. OAuth callback endpoints:
  • GET /anthropic/callback - Claude OAuth
  • GET /codex/callback - Codex OAuth
  • GET /google/callback - Google/Gemini OAuth
  • GET /iflow/callback - iFlow OAuth
  • GET /antigravity/callback - Antigravity OAuth

​
Initiating OAuth

Use management endpoints to start OAuth flows:
Get Anthropic Auth URL
curl http://localhost:8317/v0/management/anthropic-auth-url \
  -H "Authorization: Bearer your-management-secret"
The response contains an authorization URL to visit in your browser. After authorization, the callback endpoint receives the OAuth tokens.

​
Authentication Directory

OAuth tokens and authentication files are stored in the auth directory:
config.yaml
auth-dir: "~/.cli-proxy-api"  # Supports ~ for home directory
Authentication files can be managed via the Management API:
List Auth Files
curl http://localhost:8317/v0/management/auth-files \
  -H "Authorization: Bearer your-management-secret"
Upload Auth File
curl -X POST http://localhost:8317/v0/management/auth-files \
  -H "Authorization: Bearer your-management-secret" \
  -F "[email protected]" \
  -F "channel=vertex" \
  -F "prefix=prod"

​
Security Best Practices

1

Use Strong Keys

Generate cryptographically secure random keys for both API keys and management secrets:
openssl rand -hex 32
2

Restrict Management Access

Keep allow-remote: false unless you specifically need remote management access.
3

Enable TLS

Use HTTPS/TLS in production environments:
tls:
  enable: true
  cert: "/path/to/cert.pem"
  key: "/path/to/key.pem"
4

Use Environment Variables

Store sensitive keys in environment variables rather than config files:
export MANAGEMENT_PASSWORD="your-secret"
5

Rotate Keys Regularly

Implement a key rotation policy for API keys and management secrets.

​
Error Responses

​
401 Unauthorized

Returned when authentication fails: 
{
  "error": {
    "message": "invalid password",
    "type": "authentication_error"
  }
}

​
404 Not Found (Management API)

Returned when management endpoints are accessed but no secret key is configured: 
{
  "error": {
    "message": "Not Found",
    "type": "not_found"
  }
}

​
Next Steps

Chat Completions

Start making authenticated API requests

Management API

Manage API configuration and credentials

Model Configuration

Configure provider API keys and models

Security

Learn about security best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us