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

CLI Reference

Config Reference

API Reference

Troubleshooting

Architecture

Settings & Auth API

Settings & Auth API

Overview

Authentication

Profile Settings

GET /api/settings/:profile

GET /api/settings/:profile/raw

PUT /api/settings/:profile

Presets

GET /api/settings/:profile/presets

POST /api/settings/:profile/presets

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

Global Auth Tokens

GET /api/settings/auth/tokens

GET /api/settings/auth/tokens/raw

PUT /api/settings/auth/tokens

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

POST /api/settings/auth/tokens/reset

Account Management

DELETE /api/accounts/reset-default

Error Responses

Shared Data Endpoints

GET /api/shared/commands

GET /api/shared/skills

GET /api/shared/agents

GET /api/shared/content

GET /api/shared/summary

Droid Endpoints

GET /api/droid/diagnostics

GET /api/droid/settings

PUT /api/droid/settings

Config Endpoints

GET /api/config

PUT /api/config

Security Features

​Settings & Auth API

​Overview

​Authentication

​Profile Settings

​GET /api/settings/:profile

​GET /api/settings/:profile/raw

​PUT /api/settings/:profile

​Presets

​GET /api/settings/:profile/presets

​POST /api/settings/:profile/presets

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

​Global Auth Tokens

​GET /api/settings/auth/tokens

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

​PUT /api/settings/auth/tokens

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

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

​Account Management

​DELETE /api/accounts/reset-default

​Error Responses

​Shared Data Endpoints

​GET /api/shared/commands

​GET /api/shared/skills

​GET /api/shared/agents

​GET /api/shared/content

​GET /api/shared/summary

​Droid Endpoints

​GET /api/droid/diagnostics

​GET /api/droid/settings

​PUT /api/droid/settings

​Config Endpoints

​GET /api/config

​PUT /api/config

​Security Features

Settings & Auth API

Overview

Authentication

Profile Settings

GET /api/settings/:profile

GET /api/settings/:profile/raw

PUT /api/settings/:profile

Presets

GET /api/settings/:profile/presets

POST /api/settings/:profile/presets

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

Global Auth Tokens

GET /api/settings/auth/tokens

GET /api/settings/auth/tokens/raw

PUT /api/settings/auth/tokens

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

POST /api/settings/auth/tokens/reset

Account Management

DELETE /api/accounts/reset-default

Error Responses

Shared Data Endpoints

GET /api/shared/commands

GET /api/shared/skills

GET /api/shared/agents

GET /api/shared/content

GET /api/shared/summary

Droid Endpoints

GET /api/droid/diagnostics

GET /api/droid/settings

PUT /api/droid/settings

Config Endpoints

GET /api/config

PUT /api/config

Security Features