dotcom-arcade/docs/06-api-reference/settings-api.md

Settings API

Manage system-wide configuration settings.

Authentication: Required (JWT Bearer token) Permissions: settings.read (view), settings.update (modify)

Get All Settings

GET /api/settings - Requires settings.update permission

Returns grouped settings by category (auth, app, metadata, features, game).

Note: This endpoint requires settings.update (not settings.read) because it returns all settings including sensitive values.

Get Category Settings

GET /api/settings/:category - Requires settings.read permission

Returns all settings for category (auth|app|metadata|features|game).

Update Category Settings

PATCH /api/settings/:category - Requires settings.update permission

Body (all optional): { "key1": value1, "key2": value2, ... }

Validates all values against JSON schemas. Type must match setting's value_type.

Get Single Setting

GET /api/settings/:category/:key - Requires settings.read permission

Returns { "value": ... }

Update Single Setting

PATCH /api/settings/:category/:key - Requires settings.update permission

Body: { "value": ... }

Cache Management

Get Cache Stats

GET /api/settings/_cache/stats - Admin only

Returns keyCount, categoryCount, hitRate, size.

Clear Settings Cache

POST /api/settings/_cache/clear - Admin only

Body (optional): { "category": "auth" } (clear specific category or all if not provided)

Get Permission Cache Stats

GET /api/settings/_cache/permissions/stats - Requires auth + settings.update permission

Returns statistics about the permission cache.

Response:

{
  "userCacheSize": 42,
  "roleCacheSize": 3,
  "totalSize": 45,
  "description": {
    "userCacheSize": "Number of cached user permissions",
    "roleCacheSize": "Number of cached role permissions",
    "totalSize": "Total cached entries",
    "ttl": {
      "userPermissions": "5 minutes",
      "rolePermissions": "10 minutes"
    }
  }
}

Clear Permission Cache

POST /api/settings/_cache/permissions/clear - Requires auth + settings.update permission

Clears permission cache entries.

Request Body Options:

Body	Description
{ "type": "user", "id": 5 }	Clear cache for user ID 5
{ "type": "role", "id": 2 }	Clear cache for role ID 2 (also clears all user caches)
{ "type": "users" }	Clear all user permission caches
{ "type": "roles" }	Clear all role permission caches
{ "type": "all" }	Clear all permission caches

Response:

{
  "message": "Permission cache cleared successfully"
}

Settings Categories

Category	Setting	Type	Default	Validation
auth	guestAccessEnabled	boolean	true	-
auth	userRegistrationEnabled	boolean	true	-
auth	maxLoginAttempts	number	5	1-20
auth	lockoutDurationMinutes	number	15	1-1440
app	siteName	string	Dotcom Arcade	maxLength: 100
app	maintenanceMode	boolean	false	-
app	defaultTheme	string	dark	light|dark|system
app	defaultPrimaryColor	string	blue	blue|green|red|purple|orange|pink
metadata	autoSyncEnabled	boolean	false	-
metadata	syncIntervalMinutes	number	60	0-1440
features	enablePlaylists	boolean	true	-
features	enableFavorites	boolean	true	-
features	enableStatistics	boolean	true	-
features	enableActivityLog	boolean	true	-
features	enableRatings	boolean	true	-
features	enableLuckyButton	boolean	true	-
features	enableDownloadedPage	boolean	true	-
features	enableDownloadedPageForGuests	boolean	false	-
features	enableDownloadedFilterDefault	boolean	false	-
game	defaultScaleMode	string	showall	showall|exactfit|noborder|noscale
game	defaultVolume	number	0.7	0-1

Implementation Notes

Caching: Settings cached 60 seconds (in-memory). Auto-invalidated on update.

Validation: All updates validated against JSON schemas. Type, range, and enum validation enforced.

Public Settings: Runtime Injection

The GET /api/settings/public endpoint includes metadata and domains objects injected at runtime (not stored in the system_settings table):

{
  "app": { ... },
  "auth": { ... },
  "metadata": {
    "flashpointEdition": "infinity",
    "flashpointVersion": "Flashpoint 14.0.3 Infinity - Kingfisher",
    "flashpointPackagedAt": "2025-11-20T12:17:38.000Z",
    "flashpointLastUpdate": "2026-02-13T10:57:46.117Z"
  },
  "domains": {
    "defaultDomain": "play.example.com"
  }
}

Field	Source	Null when
flashpointEdition	version.txt, read once at startup	Never — defaults to "infinity"
flashpointVersion	version.txt, read once at startup	Never — empty string when the file is missing
flashpointPackagedAt	Modification time of version.txt or .preferences.defaults.json, read once at startup	Neither file exists
flashpointLastUpdate	preferences.json → newest gameMetadataSources[].games.actualUpdateTime	No source, unparseable, or the 1970-01-01 placeholder

Edition, version, and package date come from the backend config object (see Flashpoint Edition Auto-Detection); a restart is needed to pick up a changed install. The last update is read per request through PreferencesService, which caches preferences.json for 60 seconds. Clients should render flashpointLastUpdate: null as "Never" — the epoch placeholder is normalized away server-side.

Domains are managed via the separate /api/domains endpoints (see Domains API).

Frontend Integration

import { systemSettingsApi } from '@/lib/api';

// Get all
const all = await systemSettingsApi.getAll();

// Get category
const auth = await systemSettingsApi.getCategory('auth');

// Update category
await systemSettingsApi.updateCategory('auth', {
  guestAccessEnabled: false,
  maxLoginAttempts: 3,
});

// Get single
const { value } = await systemSettingsApi.getSetting(
  'auth',
  'guestAccessEnabled'
);

// Update single
await systemSettingsApi.updateSetting('auth', 'guestAccessEnabled', false);

Best Practices

• Always validate before updating (schemas enforced server-side)
• Clear cache after direct database updates
• Test setting changes before applying to production
• Document new settings in validation schemas
• Set sensible defaults
• Store values correctly (booleans as booleans, not strings)