Settings

Support reference for `/org-settings`.

- `/org-settings` redirects to `/org-settings/organization` - Tabs: - `Organization` - `Webchat` - `API Keys` - Shared shell: - layout title: `Settings` - description: `Manage your organization settings and customizations.`

- Page title: `Organization` - Description: `Manage your organization's general settings` - Current editable items: - `Organization Name` - `Debug Mode` - `Logo` upload is present but disabled with `Coming soon`. - Save button label: `Save` - Permission note: - the frontend enables editing only for org `admin` / `owner` users, plus developer users via `canAccessTool({ isOrgAdmin: true })` - the backend `PUT /api/organizations/{id}` independently checks org role and rejects non-admin members with `403` - Backend/data flow: - the page only sends `name` or `is_debug_mode` - the route is `PUT /api/organizations/{id}` - the broader update payload also supports provider API keys and `description`, but those fields are not exposed on this page - websocket refresh comes through `organization.updated`

- Focus: appearance settings plus live preview. - Widget domain choices: - `alloy.cx` - `alloy.ws` - Theme choices: - `System` - `Light` - `Dark` - `Custom` - Section labels: - `Appearance` - `Widget domain` - `Theme` - `Live Preview` - Current UI controls: - minimized widget: `Bubble color`, `Icon color` - maximized widget: `Chat background`, `Primary color` - customer messages: `Bubble color`, `Text color` - agent messages: `Bubble color`, `Text color` - `Custom CSS` textarea - `System` mode preview tabs for `light` and `dark` - Footer actions: - `Reset to defaults` - `Save changes` - Confirmed backend values: - `mode`: `system`, `light`, `dark`, `custom` - `widgetDomain`: `default`, `proxy` - Permission note: - widget settings are organization-scoped and authorized by backend checks

- Backend/data flow: - `GET /api/organizations/{id}/settings/webchat-widget-settings` returns `{ settings, defaults }` - `POST /api/organizations/{id}/settings/webchat-widget-settings` upserts the stored delta and returns merged `{ settings, defaults }` - reset-to-defaults is implemented as `POST` with an empty body - defaults include additional runtime fields not currently editable in the page: - `opacity` - `primaryTextColor` - `secondaryTextColor` - `borderColor` - `systemMessageColor` - those extra fields are still part of the backend schema and are consumed by the widget runtime if present - Preview/runtime notes: - the preview loads `${NEXT_PUBLIC_API_URL}/widget/alloy-webchat-widget.js` - it initializes the widget with the org `public_api_key` - `widgetDomain: proxy` is used by backend snippet generation to switch from `API_DOMAIN` to `API_PROXY_DOMAIN`

- Page title: `API Keys` - Description: `Manage your API keys and provider credentials` - Cards: - `Providers API Keys` - `Alloy API Keys` - Provider rows: - `OpenAI` - `OpenRouter` - `Google` - `DeepSeek` - `Anthropic` - Provider key actions: - type key - `Save API Key` - `Copy to clipboard` after save - `Clear API Key` - Saved provider keys stay masked in the input. - Alloy key rows: - `Public` - `Private` - Alloy key behavior: - public key is shown directly and can be copied - private key stays masked in the UI and is fetched only when the user clicks copy - Permission note: - there is no frontend role gate on this page - provider key save and clear still go through `PUT /api/organizations/{id}`, which requires org `owner` or `admin` - private Alloy key copy is available from the API Keys page for authorized organization users

- Backend/data flow: - provider credentials save and clear through `PUT /api/organizations/{id}`

- runtime uses a matching saved provider key before falling back to the Alloy system key for the same provider - usage with org-saved provider keys is still written to token history and cost reporting, but it does not reduce org `available_tokens` - org state on this page stays in sync through `organization.updated`

- `models` and `voices` are separate tools, not `/org-settings/*` - `/system-settings` is separate from org settings