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

{
  "profile": "gemini",
  "settings": {
    "env": {
      "ANTHROPIC_BASE_URL": "http://127.0.0.1:8317/api/provider/gemini",
      "ANTHROPIC_AUTH_TOKEN": "********",
      "ANTHROPIC_MODEL": "gemini-3-flash-preview"
    }
  },
  "mtime": 1704467400000,
  "path": "/home/user/.ccs/gemini.settings.json"
}

{
  "error": "Settings not found"
}
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

{
  "profile": "gemini",
  "settings": {
    "env": {
      "ANTHROPIC_BASE_URL": "http://127.0.0.1:8317/api/provider/gemini",
      "ANTHROPIC_AUTH_TOKEN": "actual-token-here",
      "ANTHROPIC_MODEL": "gemini-3-flash-preview"
    }
  },
  "mtime": 1704467400000,
  "path": "/home/user/.ccs/gemini.settings.json"
}

​
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
  }'

{
  "profile": "gemini",
  "mtime": 1704467500000,
  "backupPath": "/home/user/.ccs/backups/gemini.2026-01-05T14-30-00.settings.json",
  "created": false
}

{
  "profile": "glm",
  "mtime": 1704467500000,
  "created": true,
  "warning": "Missing fields will use defaults: ANTHROPIC_BASE_URL",
  "missingFields": ["ANTHROPIC_BASE_URL"]
}

{
  "error": "File modified externally",
  "currentMtime": 1704467450000
}
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

{
  "presets": [
    {
      "name": "Opus Thinking",
      "default": "gemini-claude-opus-4-5-thinking",
      "opus": "gemini-claude-opus-4-5-thinking",
      "sonnet": "gemini-claude-opus-4-5-thinking",
      "haiku": "gemini-3-flash-preview"
    },
    {
      "name": "Balanced",
      "default": "gemini-claude-sonnet-4",
      "opus": "gemini-claude-opus-4-5",
      "sonnet": "gemini-claude-sonnet-4",
      "haiku": "gemini-claude-haiku-4"
    }
  ]
}

​
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"
  }'

{
  "preset": {
    "name": "Custom Mix",
    "default": "gemini-claude-sonnet-4",
    "opus": "gemini-claude-opus-4-5",
    "sonnet": "gemini-claude-sonnet-4",
    "haiku": "gemini-3-flash-preview"
  }
}

{
  "error": "Preset with this name already exists"
}

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

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

{
  "success": true
}

{
  "error": "Preset not found"
}

​
Global Auth Tokens

​
GET /api/settings/auth/tokens

Get current auth token status with masked values. 
curl http://localhost:3000/api/settings/auth/tokens

{
  "apiKey": {
    "value": "ccs_********************************",
    "isCustom": false
  },
  "managementSecret": {
    "value": "********",
    "isCustom": true
  }
}
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

{
  "apiKey": {
    "value": "ccs_1234567890abcdef1234567890abcdef",
    "isCustom": false
  },
  "managementSecret": {
    "value": "my-secret-key-12345",
    "isCustom": true
  }
}

​
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"
  }'

{
  "success": true,
  "apiKey": {
    "value": "ccs_********************************",
    "isCustom": true
  },
  "managementSecret": {
    "value": "********",
    "isCustom": true
  },
  "message": "Restart CLIProxy to apply changes"
}
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

{
  "success": true,
  "managementSecret": {
    "value": "********",
    "isCustom": true
  },
  "message": "Restart CLIProxy to apply changes"
}

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

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

{
  "success": true,
  "apiKey": {
    "value": "ccs_********************************",
    "isCustom": false
  },
  "managementSecret": {
    "value": "********",
    "isCustom": false
  },
  "message": "Tokens reset to defaults. Restart CLIProxy to apply."
}

​
Account Management

​
DELETE /api/accounts/reset-default

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

{
  "success": true,
  "message": "Default account reset to CCS"
}

​
Error Responses

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

{
  "error": "Settings not found"
}

{
  "error": "File modified externally",
  "currentMtime": 1704467450000
}

{
  "error": "Failed to write settings file",
  "message": "Detailed error message"
}

​
Shared Data Endpoints

Available since v7.48.0

​
GET /api/shared/commands

List all shared commands with descriptions.

​
GET /api/shared/skills

List all shared skills with descriptions.

​
GET /api/shared/agents

List all shared agents with descriptions.

​
GET /api/shared/content

Load full markdown content for a shared item. Query Parameters:
  • type: commands | skills | agents
  • path: Item path

​
GET /api/shared/summary

Get counts and symlink status for all shared data types. 
{
  "commands": 5,
  "skills": 3,
  "agents": 2,
  "total": 10,
  "symlinkStatus": "ok"
}

​
Droid Endpoints

Available since v7.48.0

​
GET /api/droid/diagnostics

Get Factory Droid binary detection and configuration status.

​
GET /api/droid/settings

Read ~/.factory/settings.json with diagnostics.

​
PUT /api/droid/settings

Write to ~/.factory/settings.json with atomic write and mtime conflict detection. Request Body:
  • content: JSON string of settings
  • expectedMtime (optional): Optimistic locking timestamp

​
Config Endpoints

Available since v7.49.0

​
GET /api/config

Get current CCS config.yaml as JSON.

​
PUT /api/config

Update config.yaml with validation and conflict detection.

​
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