Settings Management

Overview

The Settings Management API provides endpoints for managing tenant settings and feature flags. Settings are stored in KV store and can be changed dynamically without redeployment.

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/settings`	Get all settings
GET	`/api/admin/settings/:category`	Get settings by category
PUT	`/api/admin/settings/:category`	Update settings by category
GET	`/api/admin/settings/feature-flags`	List feature flags
PUT	`/api/admin/settings/feature-flags/:flag`	Update feature flag
POST	`/api/admin/settings/reset/:category`	Reset settings to default

Get All Settings

Retrieve all settings for the tenant.

Endpoint

GET /api/admin/settings

Request Example

curl -X GET "https://{tenant-domain}/api/admin/settings" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "authentication": {
    "password_policy": {
      "min_length": 8,
      "require_uppercase": true,
      "require_lowercase": true,
      "require_numbers": true,
      "require_symbols": false,
      "max_age_days": 90
    },
    "session": {
      "lifetime": 86400,
      "idle_timeout": 3600,
      "absolute_timeout": 604800,
      "single_session": false
    },
    "mfa": {
      "enabled": true,
      "required": false,
      "methods": ["totp", "sms", "email"]
    },
    "lockout": {
      "enabled": true,
      "max_attempts": 5,
      "lockout_duration": 900
    }
  },
  "branding": {
    "logo_url": "https://example.com/logo.png",
    "primary_color": "#0066CC",
    "company_name": "Example Corp"
  },
  "email": {
    "from_address": "[email protected]",
    "from_name": "Example Corp"
  },
  "security": {
    "allowed_origins": ["https://app.example.com"],
    "trusted_proxies": [],
    "rate_limiting": {
      "enabled": true,
      "requests_per_minute": 60
    }
  }
}

Get Settings by Category

Retrieve settings for a specific category.

Endpoint

GET /api/admin/settings/:category

Path Parameters

Parameter	Type	Required	Description
`category`	string	✓	Settings category

Settings Categories

Category	Description
`authentication`	Authentication-related settings
`branding`	Branding settings
`email`	Email settings
`security`	Security settings
`tokens`	Token settings
`webhooks`	Webhook settings
`compliance`	Compliance settings

Request Example

curl -X GET "https://{tenant-domain}/api/admin/settings/authentication" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "password_policy": {
    "min_length": 8,
    "require_uppercase": true,
    "require_lowercase": true,
    "require_numbers": true,
    "require_symbols": false,
    "max_age_days": 90,
    "history_count": 5
  },
  "session": {
    "lifetime": 86400,
    "idle_timeout": 3600,
    "absolute_timeout": 604800,
    "single_session": false,
    "remember_me_enabled": true,
    "remember_me_duration": 2592000
  },
  "mfa": {
    "enabled": true,
    "required": false,
    "methods": ["totp", "sms", "email"],
    "grace_period": 0
  },
  "lockout": {
    "enabled": true,
    "max_attempts": 5,
    "lockout_duration": 900,
    "reset_after": 3600
  }
}

Update Settings by Category

Update settings for a specific category.

Endpoint

PUT /api/admin/settings/:category

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/settings/authentication" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "password_policy": {
      "min_length": 12,
      "require_symbols": true
    },
    "mfa": {
      "required": true
    }
  }'

Response Example

{
  "updated": true,
  "category": "authentication",
  "changes": {
    "password_policy.min_length": {
      "old": 8,
      "new": 12
    },
    "password_policy.require_symbols": {
      "old": false,
      "new": true
    },
    "mfa.required": {
      "old": false,
      "new": true
    }
  },
  "updated_at": 1706140800
}

List Feature Flags

Retrieve feature flags for the tenant.

Endpoint

GET /api/admin/settings/feature-flags

Request Example

curl -X GET "https://{tenant-domain}/api/admin/settings/feature-flags" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "flags": [
    {
      "key": "passwordless_enabled",
      "display_name": "Passwordless Authentication",
      "description": "Enable passwordless authentication with WebAuthn/Passkeys",
      "enabled": false,
      "category": "authentication",
      "impact": "low"
    },
    {
      "key": "advanced_mfa",
      "display_name": "Advanced MFA",
      "description": "Enable risk-based MFA and adaptive authentication",
      "enabled": true,
      "category": "security",
      "impact": "medium"
    },
    {
      "key": "rebac_enabled",
      "display_name": "ReBAC",
      "description": "Enable relationship-based access control",
      "enabled": true,
      "category": "access_control",
      "impact": "high"
    },
    {
      "key": "audit_log_export",
      "display_name": "Audit Log Export",
      "description": "CSV/JSON export functionality for audit logs",
      "enabled": true,
      "category": "compliance",
      "impact": "low"
    }
  ]
}

Update Feature Flag

Update a specific feature flag.

Endpoint

PUT /api/admin/settings/feature-flags/:flag

Path Parameters

Parameter	Type	Required	Description
`flag`	string	✓	Feature flag key

Request Body

Field	Type	Required	Description
`enabled`	boolean	✓	Enable/disable

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/settings/feature-flags/passwordless_enabled" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

Response Example

{
  "key": "passwordless_enabled",
  "enabled": true,
  "updated_at": 1706227200
}

Reset Settings to Default

Reset settings for a specific category to default values.

Endpoint

POST /api/admin/settings/reset/:category

Path Parameters

Parameter	Type	Required	Description
`category`	string	✓	Settings category

Request Example

curl -X POST "https://{tenant-domain}/api/admin/settings/reset/authentication" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "reset": true,
  "category": "authentication",
  "reset_at": 1706313600
}

Settings Priority

Settings values are resolved in the following priority order:

KV Store (set via Admin API) - Highest priority
Environment variables - Set at deployment
Code default values - Lowest priority

Example: Minimum password length
KV: 12 → Used
Environment variable: MIN_PASSWORD_LENGTH=10
Code default: 8

Settings Change Audit

All settings changes are recorded in audit logs. Filter by action: settings.update in the Audit Logs API to review.