Settings

The Settings area (/settings/) is the single location for organization-wide configuration, your personal account, API access, module enablement, and integration wiring. Every sub-page is reachable from the collapsible left sidebar inside Settings or directly by URL.

Access requires the settings:read permission. Installing or removing plugins additionally requires settings:admin. Super-admins and admins have both by default.

Navigation

Bare /settings redirects to /settings/general/. Use the left sidebar to jump to any category, or append the tab slug directly to the URL: /settings/api-keys/, /settings/modules/, etc.

---

Valid tabs

URL slug	Section	What you configure
general	Organization	Org name, description, timezone, date format, language
appearance	Organization	Theme, accent color, animation toggle
sso	Security & Access	OIDC / LDAP identity providers
api-keys	Security & Access	Create and revoke scoped API keys
oauth2-apps	Security & Access	Register OAuth2 applications for Auth Code flow
ai	Integrations	AI provider credentials and governance
notifications	Integrations	Notification preferences and channel subscriptions
modules	System	Per-module enable/disable
system	System	Live infrastructure health and version info

---

Organization settings

General - /settings/general/

The General tab lets you update the fields that were set during the setup wizard. Changes are written immediately via PATCH /organizations/{id}.

Field	Notes
Organization name	Displayed in the UI header and org-management pages
Description	Freeform; shown on the organization detail page
Timezone	Used for scheduled-task time display and log timestamps
Date format	Affects all date columns across the UI
Language	Sets the default locale for this organization; individual users can override in their browser

Appearance - /settings/appearance/

Appearance settings are stored in browser-local Zustand persist and apply immediately without a page reload.

Setting	Options
Theme	Light / Dark / System
Accent color	A set of preset palette choices
Animations	Toggle route transition animations on or off

These settings are per-browser, not per-user-account. They do not sync across devices.

---

User profile and MFA

Your profile is not inside the Settings sidebar - it is accessed from the user menu at the top-right of the TopBar.

Editing your profile

Click your name in the user menu, then Profile. The dialog exposes:

Action	API call
Change display name	PATCH /users/{id}
Change email address	PATCH /users/{id}
Change password	POST /auth/password
Delete account	Not available as a self-service action. DELETE /users/{id} requires admin role and explicitly rejects the caller’s own ID - any attempt to delete your own account returns 400 Cannot delete yourself. Account deletion must be requested from an administrator.

Changing your password

1. Open the user menu → Profile → Change Password.
2. Enter your current password, then a new password meeting all five rules.
3. Submit - all existing sessions (including the current one) are invalidated. You will be signed out and prompted to log in again with your new password. All API keys are also revoked and must be recreated.

Password rules (enforced client-side and server-side):

Rule	Minimum
Length	12 characters
Uppercase letters	1
Lowercase letters	1
Digits	1
Special characters	1

Enrolling TOTP MFA

1. Open the user menu → Profile.
2. The dialog shows your current MFA status. Click Enable.
3. Scan the QR code with an authenticator app (Google Authenticator, Authy, etc.).
4. Enter the six-digit code to confirm enrollment.
5. Copy your backup codes now. They are shown exactly once.

Backup codes are shown once

Backup codes are displayed only at enrollment time and are not recoverable from the UI. If you lose your TOTP device and have no backup codes, regaining access requires database-level intervention. Store backup codes in a password manager or offline in a secure location.

To re-enroll or disable MFA after initial setup, go through the same profile dialog. The MFA “Manage” link in the profile dialog references /settings/security/ - note that security is not a valid Settings tab; the working path is through the profile dialog itself.

TOTP is the only supported second factor

FreeSDN supports TOTP (time-based one-time password) and backup codes. Hardware security keys (FIDO2/WebAuthn) are not currently supported.

---

API keys - /settings/api-keys/

API keys let external scripts, CI pipelines, and integrations authenticate without a user session. Each key acts as a hard permission ceiling: it cannot grant more access than the creating user’s own permissions, even if the creator is a super-admin.

Creating a key

1. Go to Settings → API Keys.
2. Click Create API Key.
3. Give the key a descriptive name (you will see only the name later, not the key value).
4. Select a permission scope from the list of available scopes.
5. Optionally set an expiry date.
6. Click Create - copy the full key value now.

The key value is shown exactly once

After you close the creation dialog, FreeSDN stores only a hashed token. You cannot retrieve the plaintext key again. If you lose it, revoke the key and create a new one.

Using a key

Pass the key in the Authorization header:

Authorization: Bearer <your-api-key>

The key is subject to the same rate limits as interactive sessions (600 requests/minute per principal by default, 5/minute for auth endpoints).

Revoking a key

Click the Revoke action on any key row. Revocation is immediate - any in-flight request using that key will receive 401 on its next attempt.

Key endpoints:

Method	Path	Purpose
GET	/api/v1/api-keys	List your API keys (names and metadata, no secrets)
POST	/api/v1/api-keys	Create a new key
DELETE	/api/v1/api-keys/{key_id}	Revoke a key

---

OAuth2 apps - /settings/oauth2-apps/

The OAuth2 Apps tab lets you register client applications that use the Authorization Code flow to obtain user-scoped tokens on behalf of your users. This is intended for first-party tooling and trusted internal apps.

Field	Notes
App name	Shown in the consent prompt
Redirect URIs	One per line; must match exactly during the auth flow
Scopes	The maximum scopes the app is permitted to request

After registration, you receive a client_id and a client_secret. The secret is shown once at registration time.

---

SSO - /settings/sso/

The SSO tab embeds SSOSettingsPage and manages identity provider (IdP) records for your organization.

Protocol	Status
OIDC (OpenID Connect)	Working
LDAP	Working
SAML	501-gated - not available

SAML is disabled

The SAML authentication path returns 501 Not Implemented. Do not configure an IdP and expect SAML logins to succeed - every attempt will be rejected. SAML is not available in this release.

Adding an OIDC provider

1. Click Add Provider and select OIDC.
2. Enter an IdP name (shown on the login page), the discovery URL (e.g. https://accounts.google.com/.well-known/openid-configuration) or manual endpoint URLs, client ID, and client secret.
3. Click Save, then Test to verify the configuration.
4. A button for this IdP now appears on the /login page.

Users who authenticate via OIDC are redirected to /auth/sso/callback, which validates the state parameter, completes the login, and routes them onward. If MFA is also required, the callback handles the MFA-pending state before navigating to the dashboard.

Adding an LDAP provider

1. Click Add Provider and select LDAP.
2. Enter the LDAP server URL, bind DN, bind password, base DN for user search, and the attribute to map to FreeSDN username.
3. Save and test.

LDAP users are authenticated against the directory on every login; FreeSDN does not cache LDAP passwords.

---

Modules - /settings/modules/

The Modules tab shows a table of every module available to your organization with its current enabled/disabled state. Toggle a module by clicking the switch in its row.

Column	Meaning
Module name	Human-readable name and internal ID
Status	Enabled / Disabled
Version	Module version string
Actions	Click the row to open the module detail page

What changes when you disable a module:

Surface	Effect
Sidebar nav items	Hidden immediately for all users in the org
Direct URL navigation	Shows a “Module Disabled” page - no crash or blank
Backend API endpoints	Still respond; the frontend simply stops calling them
Stored data	Retained - disabling is not deletion
Re-enabling	Immediate; data and settings are restored

Disabling does not require a server restart.

Module detail page - /settings/modules/{moduleId}/

Click any module row to open its detail page. Here you can:

• Read the module description and see which adapters it uses
• View the current version and adapter registration status
• Enable, disable, or request a reload of the module

Gated: settings:read for viewing; the enable/disable toggle and reload button require org_admin role or above.

Access Control is coming soon; AI is beta

Access Control (access_control) is coming soon - it is disabled by default and cannot be enabled yet. Door lock/unlock returns 501 because no door adapter ships yet. The AI Assistant (ai) is functional but requires a configured AI provider and careful governance review before production use.

---

Notifications - /settings/notifications/

The Notifications tab controls personal notification preferences for the currently logged-in user. It does not manage notification providers (those live at /notification-providers/) - it controls how and when notifications are delivered to you.

Setting group	What you configure
General preferences	Default severity threshold for alerts to notify you
Quiet hours	Time window during which non-critical notifications are suppressed
Category × channel matrix	Which event categories (alerts, security, system, agent, backup, …) go to which channels (in-app, email, Slack, etc.)
Digest settings	Batch notifications into a periodic digest instead of per-event delivery
Provider summary	Read-only view of which providers are active for your org

Changes are saved per-user and do not affect other users’ preferences.

In-app notification inbox

The bell icon in the TopBar opens an in-app notification drawer with:

• Active and Archive tabs
• Unread badge count
• Per-notification mark-as-read, dismiss, and click-to-navigate (goes to the notification’s action_url)
• Mark-all-read, clear-all
• “Load more” pagination for older notifications

Notifications are backed by /notifications/ endpoints. They are org-scoped and respect the site filter.

---

AI settings - /settings/ai/

The AI tab configures LLM provider credentials and governs when and how the AI Assistant is permitted to make external API calls.

Governance model

FreeSDN enforces a three-layer AI governance hierarchy:

Layer	Scope	Default
Global kill-switch	Platform-wide	Off - AI features inactive until enabled
Per-org policy	Per organization	DISABLED / LOCAL_ONLY / CLOUD_APPROVED
PII redaction	Every cloud call	Active - PII is stripped before data leaves the instance

Global kill-switch defaults off

The AI Assistant does nothing until a super-admin enables the global kill-switch. Even after enabling it, each organization must set its policy to LOCAL_ONLY (Ollama only) or CLOUD_APPROVED (OpenAI / Anthropic allowed) before users can invoke AI tools.

Supported providers

Provider	Type	Notes
OpenAI	Cloud	Requires an OpenAI API key; base URL overrideable for Azure / compatible endpoints
Anthropic	Cloud	Requires an Anthropic API key
Ollama	Local	Requires a running Ollama instance accessible from the FreeSDN API container; set base URL

FreeSDN communicates with all three via httpx directly - no vendor SDK packages are bundled.

Adding a provider

1. Go to Settings → AI.
2. Select the provider tab (OpenAI / Anthropic / Ollama).
3. Enter the API key (OpenAI / Anthropic) or base URL (Ollama).
4. Optionally set the default model name.
5. Click Test Connectivity to verify the credential before saving.

If the test fails, the credential is not saved. Check that the API key is valid and that the FreeSDN API container has outbound network access to the provider endpoint.

---

System info - /settings/system/

The System tab is read-only. It displays a live snapshot of infrastructure health sourced from GET /enterprise/health/infrastructure:

Section	What you see
Platform	FreeSDN version, Python runtime version, FastAPI version
Library versions	SQLAlchemy, Pydantic, Celery, and other key dependencies
PostgreSQL	Version, connection pool stats
Redis / Valkey	Version, connection status
Celery	Active workers, beat scheduler status
Uptime	API process uptime
Route counts	Total registered routes, active modules, registered adapters

This page is useful for verifying that a deployment is running the expected version and that all backing services are reachable. It does not allow changes.

Valkey replaces Redis

FreeSDN migrated from Redis to Valkey 8.1 as the cache, broker, and results backend. The service name and redis:// URL scheme are retained for drop-in compatibility. The System tab reports “Redis / Valkey” to reflect this.

---

Integrations reference

Integrations that wire FreeSDN to external systems live across two places:

Location	What you wire
/settings/sso/	Identity providers (OIDC, LDAP)
/settings/ai/	LLM providers (OpenAI, Anthropic, Ollama)
/integrations/	Guided typed integrations (n8n, Slack, PagerDuty, and others), each backed by a Webhook record with delivery history and dead-letter queue replay
/notification-providers/	Notification channel providers (Email, Slack, SMS, Teams, Webhook) - global only (hidden in nav when a specific site is selected; any authenticated user can view providers, but creating/editing/deleting requires org_admin or above)
/webhooks/	Raw webhook CRUD and delivery history
/fabric/	Universal app-interconnect (event → step-chain Connections across modules)

Notification providers vs notification settings

/notification-providers/ manages the channels available to the org (e.g., “the Slack workspace for Ops”). /settings/notifications/ manages your personal subscription preferences against those channels. Both must be configured for end-to-end delivery to work.

---

Permission reference

Permission	Who needs it	What it gates
settings:read	Required for all /settings/* pages	View any settings tab, manage API keys
org_admin role (or above)	Required to change module state	Enable / disable modules for the organization (POST /modules/org/{id}/enable and /disable)
settings:admin	Required for plugins and marketplace	Install / remove plugins; browse and install marketplace extensions
user:read	Users page	View and manage other users (separate from Settings)
role:read	Roles page	View the role and permission matrix (separate from Settings)

A user with viewer role (tier 10) does not have settings:read and will be redirected to /unauthorized when navigating to /settings/.

---

Next steps

• Add notification providers for your team’s channels (Slack, email, PagerDuty) at the /notification-providers/ page before configuring alert rules.
• Create API keys for any scripts or pipelines that need programmatic access - see the API reference for available endpoints and authentication details.
• Register SSO if your organization uses an OIDC-compatible identity provider so users can log in without a local password.
• Review module enablement after adding new controllers - if you add a Proxmox host, enable Compute / Hypervisor here before navigating to /hypervisor/.
• Configure AI governance before enabling the AI Assistant for any user - set the global kill-switch, choose a per-org policy, and verify PII redaction is active for any cloud provider.