Skip to main content

​
Settings & Auth API

Manage profile settings, create presets for quick configuration switching, and control global authentication tokens for CLIProxy.

​
Overview

Settings endpoints provide:
  • Profile settings CRUD (Create, Read, Update, Delete)
  • Preset management for model configurations
  • Global auth token management (API key, management secret)
  • Token regeneration and reset
  • Conflict detection with optimistic locking

​
Authentication

All endpoints are available on localhost only (http://localhost:3000). No authentication required.

​
Profile Settings

​
GET /api/settings/:profile

Get settings for a profile with masked API keys. Path Parameters:
  • profile: Profile name or variant (e.g., gemini, glm, agy)
curl http://localhost:3000/api/settings/gemini
Note: Sensitive keys (API tokens, secrets) are automatically masked with ********.

​
GET /api/settings/:profile/raw

Get full unmasked settings for editing.
Sensitive endpoint - returns unmasked API keys. Use for editing only.
curl http://localhost:3000/api/settings/gemini/raw

​
PUT /api/settings/:profile

Update settings with conflict detection and automatic backup. Path Parameters:
  • profile: Profile name or variant
Request Body:
  • settings (required): Settings object with env field
  • expectedMtime (optional): Timestamp for optimistic locking
curl -X PUT http://localhost:3000/api/settings/gemini \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "env": {
        "ANTHROPIC_BASE_URL": "http://127.0.0.1:8317/api/provider/gemini",
        "ANTHROPIC_AUTH_TOKEN": "new-token",
        "ANTHROPIC_MODEL": "gemini-3-pro-preview"
      }
    },
    "expectedMtime": 1704467400000
  }'
Features:
  • Optimistic Locking: Uses expectedMtime to detect concurrent edits
  • Automatic Backup: Creates backup before modification in ~/.ccs/backups/
  • Atomic Write: Temp file + rename for crash safety
  • Validation Warning: Alerts if required fields missing (non-blocking)

​
Presets

​
GET /api/settings/:profile/presets

Get saved presets for a profile. 
curl http://localhost:3000/api/settings/gemini/presets

​
POST /api/settings/:profile/presets

Create a new preset configuration. Request Body:
  • name (required): Preset name
  • default (required): Default model
  • opus (optional): Opus tier model
  • sonnet (optional): Sonnet tier model
  • haiku (optional): Haiku tier model
curl -X POST http://localhost:3000/api/settings/gemini/presets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Mix",
    "default": "gemini-claude-sonnet-4",
    "opus": "gemini-claude-opus-4-5",
    "sonnet": "gemini-claude-sonnet-4",
    "haiku": "gemini-3-flash-preview"
  }'

​
DELETE /api/settings/:profile/presets/:name

Delete a preset by name. 
curl -X DELETE http://localhost:3000/api/settings/gemini/presets/Custom%20Mix

​
Global Auth Tokens

​
GET /api/settings/auth/tokens

Get current auth token status with masked values. 
curl http://localhost:3000/api/settings/auth/tokens
Fields:
  • isCustom: true if user-provided, false if default

​
GET /api/settings/auth/tokens/raw

Get unmasked auth tokens.
Sensitive endpoint - returns unmasked secrets. No caching headers applied.
curl http://localhost:3000/api/settings/auth/tokens/raw

​
PUT /api/settings/auth/tokens

Update global auth tokens and regenerate CLIProxy config. Request Body:
  • apiKey (optional): New API key (empty string to reset to default)
  • managementSecret (optional): New management secret
curl -X PUT http://localhost:3000/api/settings/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "ccs_new-api-key-here",
    "managementSecret": "new-secret-123"
  }'
Changes require CLIProxy restart to take effect. Config is regenerated automatically.

​
POST /api/settings/auth/tokens/regenerate-secret

Generate a new 32-character management secret. 
curl -X POST http://localhost:3000/api/settings/auth/tokens/regenerate-secret

​
POST /api/settings/auth/tokens/reset

Reset auth tokens to defaults. 
curl -X POST http://localhost:3000/api/settings/auth/tokens/reset

​
Account Management

​
DELETE /api/accounts/reset-default

Reset default account to CCS default. 
curl -X DELETE http://localhost:3000/api/accounts/reset-default

​
Error Responses

{
  "error": "settings object is required in request body"
}

​
Security Features

  • API Key Masking: Automatic masking for display endpoints
  • Optimistic Locking: mtime-based conflict detection prevents data loss
  • Atomic Writes: Temp file + rename ensures crash safety
  • Automatic Backups: Previous settings saved before updates
  • No Cache Headers: Sensitive endpoints (/raw, /auth/tokens/raw) prevent caching
  • Localhost Only: API only accessible on 127.0.0.1