Technical docs

Settings

Overview

Support reference for `/org-settings`.

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`

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

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`