Skip to main content

​
Overview

The Settings Management API allows you to retrieve and update system-wide configuration settings for Codex-LB, including routing strategy, authentication requirements, and feature flags.
All Settings endpoints require dashboard authentication via session cookie.

​
Get Settings

​
GET /api/settings
endpoint
Retrieve current system settings.

​
Response

​
sticky_threads_enabled
boolean
required
Whether to maintain thread affinity (keep same account for a conversation thread)
​
prefer_earlier_reset_accounts
boolean
required
Whether to prefer accounts with earlier reset times for load balancing
​
routing_strategy
string
required
Load balancing strategy: usage_weighted or round_robin
​
import_without_overwrite
boolean
required
Whether to skip importing accounts that already exist (by identity)
​
totp_required_on_login
boolean
required
Whether TOTP (2FA) is required for dashboard login
​
totp_configured
boolean
required
Whether TOTP has been configured for the admin user
​
api_key_auth_enabled
boolean
required
Whether API key authentication is required for proxy endpoints

​
Example Request

curl -X GET "https://your-instance.com/api/settings" \
  -H "Cookie: dashboard_session=your-session-token"

​
Example Response

{
  "sticky_threads_enabled": true,
  "prefer_earlier_reset_accounts": false,
  "routing_strategy": "usage_weighted",
  "import_without_overwrite": false,
  "totp_required_on_login": false,
  "totp_configured": true,
  "api_key_auth_enabled": true
}

​
Update Settings

​
PUT /api/settings
endpoint
Update system settings. All boolean fields are required; optional fields default to current values.

​
Request Body

​
sticky_threads_enabled
boolean
required
Enable thread affinity to keep conversations on the same account
​
prefer_earlier_reset_accounts
boolean
required
Prioritize accounts with earlier quota reset times
​
routing_strategy
string
Load balancing strategy:
  • usage_weighted: Route to accounts with more available capacity
  • round_robin: Distribute requests evenly across accounts
​
import_without_overwrite
boolean
Skip importing accounts that already exist in the database
​
totp_required_on_login
boolean
Require TOTP (2FA) verification on every dashboard login
​
api_key_auth_enabled
boolean
Require valid API key authentication for all proxy requests

​
Response

Returns the updated settings object (same structure as GET response).

​
Example Request

curl -X PUT "https://your-instance.com/api/settings" \
  -H "Cookie: dashboard_session=your-session-token" \
  -H "Content-Type: application/json" \
  -d '{
    "sticky_threads_enabled": true,
    "prefer_earlier_reset_accounts": false,
    "routing_strategy": "usage_weighted",
    "import_without_overwrite": true,
    "totp_required_on_login": true,
    "api_key_auth_enabled": true
  }'

​
Example Response

{
  "sticky_threads_enabled": true,
  "prefer_earlier_reset_accounts": false,
  "routing_strategy": "usage_weighted",
  "import_without_overwrite": true,
  "totp_required_on_login": true,
  "totp_configured": true,
  "api_key_auth_enabled": true
}

​
Error Responses

​
400
error
invalid_totp_config: Cannot enable TOTP requirement without configuring it first

​
Setting Descriptions

​
Routing Strategy

Distributes requests evenly across all active accounts, regardless of their current usage levels.Best for: Testing environments or when you want predictable distribution

​
Thread Affinity

When sticky_threads_enabled is true, requests with the same conversation thread ID are routed to the same Claude account. This can improve conversation coherence but may lead to uneven load distribution.

​
API Key Authentication

When enabling api_key_auth_enabled, ensure you have created at least one API key first. Otherwise, all proxy requests will be rejected with 401 Unauthorized.
When API key authentication is enabled:
  • All proxy endpoints (/v1/*, /backend-api/codex/*, /backend-api/transcribe) require a valid Bearer token
  • The /api/codex/usage endpoint remains accessible without authentication
  • Dashboard endpoints (/api/*) continue to use session-based authentication

​
TOTP (Two-Factor Authentication)

The totp_required_on_login setting enforces 2FA for dashboard access:
  1. First, configure TOTP in the dashboard settings (sets totp_configured: true)
  2. Then enable the requirement via this API or the dashboard UI
  3. Subsequent logins will require a TOTP code from your authenticator app
You cannot enable totp_required_on_login without first configuring TOTP. The API will return a 400 error if you try.

​
Import Behavior

When import_without_overwrite is enabled:
  • Account imports check for existing identities before inserting
  • If a matching identity exists, the import is skipped (no error)
  • This prevents duplicate accounts when re-importing the same auth.json files

​
Cache Behavior

Settings are cached in memory for performance. When you update settings via the API:
  1. Changes are written to the database
  2. The in-memory cache is invalidated
  3. Next request fetches fresh settings from the database
Changes take effect immediately for all new requests.

​
Authentication

All settings endpoints require dashboard authentication via session cookie. You must be logged in as an admin to view or modify settings.

​
Common Error Codes

CodeDescription
invalid_totp_configAttempted to enable TOTP requirement without configuring it first
unauthorizedMissing or invalid dashboard session cookie

Build docs developers (and LLMs) love

Get started for freeTalk to us