Skip to content
Fluxbase

User Settings

User settings provide per-user, key-value configuration storage. Fluxbase supports both plaintext settings (for preferences) and encrypted secrets (for sensitive values like API tokens).

Overview

Section titled “Overview”

User settings enable:

  • Per-user configuration - Each user has their own settings namespace
  • System fallback - If a user hasn’t set a value, the system default is returned
  • Encrypted secrets - Store sensitive values with AES-256-GCM encryption
  • Tenant awareness - Settings respect tenant isolation via RLS

Settings are stored in app.settings and support both user-scoped and system-scoped entries.

User Settings

Section titled “User Settings”

Set a User Setting

Section titled “Set a User Setting”
Terminal window
curl -X PUT \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"value": {"theme": "dark", "language": "en"}}' \
  http://localhost:8080/api/v1/settings/user/preferences

This is an upsert operation — creating the setting if it doesn’t exist, or updating it if it does.

Get a Setting (with Fallback)

Section titled “Get a Setting (with Fallback)”
Terminal window
curl -H "Authorization: Bearer <jwt-token>" \
  http://localhost:8080/api/v1/settings/user/preferences

Returns the user’s own value if set, otherwise falls back to the system-level default:

{
  "key": "preferences",
  "value": {"theme": "dark", "language": "en"},
  "source": "user"
}

The source field is either "user" or "system".

Get User’s Own Setting Only

Section titled “Get User’s Own Setting Only”
Terminal window
curl -H "Authorization: Bearer <jwt-token>" \
  http://localhost:8080/api/v1/settings/user/own/preferences

Returns only the user’s own setting — no system fallback. Returns 404 if the user hasn’t set it.

Get a System Setting

Section titled “Get a System Setting”
Terminal window
curl -H "Authorization: Bearer <jwt-token>" \
  http://localhost:8080/api/v1/settings/user/system/preferences

Returns the system-level default for a key.

List All User Settings

Section titled “List All User Settings”
Terminal window
curl -H "Authorization: Bearer <jwt-token>" \
  http://localhost:8080/api/v1/settings/user/list

Delete a User Setting

Section titled “Delete a User Setting”
Terminal window
curl -X DELETE \
  -H "Authorization: Bearer <jwt-token>" \
  http://localhost:8080/api/v1/settings/user/preferences

User Secrets

Section titled “User Secrets”

Secrets are encrypted at rest and never returned via the API. Only metadata (key, description, timestamps) is exposed. Secret values are encrypted with a user-specific derived key.

Create a Secret

Section titled “Create a Secret”
Terminal window
curl -X POST \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"key": "third_party_api_key", "value": "sk-abc123", "description": "External API key"}' \
  http://localhost:8080/api/v1/settings/secret

Response contains only metadata — the value is never returned:

{
  "id": "uuid",
  "key": "third_party_api_key",
  "description": "External API key",
  "user_id": "uuid",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:00Z"
}

List Secrets

Section titled “List Secrets”
Terminal window
curl -H "Authorization: Bearer <jwt-token>" \
  http://localhost:8080/api/v1/settings/secret

Get Secret Metadata

Section titled “Get Secret Metadata”
Terminal window
curl -H "Authorization: Bearer <jwt-token>" \
  http://localhost:8080/api/v1/settings/secret/third_party_api_key

Update a Secret

Section titled “Update a Secret”
Terminal window
curl -X PUT \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"value": "sk-newkey456", "description": "Updated API key"}' \
  http://localhost:8080/api/v1/settings/secret/third_party_api_key

Delete a Secret

Section titled “Delete a Secret”
Terminal window
curl -X DELETE \
  -H "Authorization: Bearer <jwt-token>" \
  http://localhost:8080/api/v1/settings/secret/third_party_api_key

API Endpoints

Section titled “API Endpoints”

User Settings

Section titled “User Settings”
Method Endpoint Description
GET /api/v1/settings/user/list List all user settings
GET /api/v1/settings/user/:key Get setting (with fallback)
GET /api/v1/settings/user/own/:key Get user’s own setting only
GET /api/v1/settings/user/system/:key Get system default
PUT /api/v1/settings/user/:key Set (upsert) a user setting
DELETE /api/v1/settings/user/:key Delete a user setting

User Secrets

Section titled “User Secrets”
Method Endpoint Description
POST /api/v1/settings/secret Create a secret
GET /api/v1/settings/secret List secrets
GET /api/v1/settings/secret/* Get secret metadata
PUT /api/v1/settings/secret/* Update a secret
DELETE /api/v1/settings/secret/* Delete a secret

All endpoints require authentication.

App Settings (Public)

Section titled “App Settings (Public)”

The global settings endpoint provides read access to application settings without authentication:

Method Endpoint Description
GET /api/v1/settings/:key Get a setting by key
GET /api/v1/settings/ Batch get settings
POST /api/v1/settings/batch Batch get by keys

Learn More

Section titled “Learn More”