public-api-docs

User API Settings Guide

Overview

Settings let operator-built user apps read tenant-managed configuration from the platform. Operators can add their own settings in the APP area, and the app can retrieve those settings through the User API. This gives operators freedom to configure feature flags, app behavior, thresholds, URLs, labels, rollout switches, or white-label content without shipping a new app build.

The User API reads settings for the app. Creating, updating, deleting, or importing settings is handled through Operations API/admin settings management.

Related reference: User API User API Guide Localization Guide

Core Concepts

Setting Keys

A setting is identified by a stable key. The app references the key in code and reads the configured value from the API.

Example app-owned keys:

app.home.show_wallet_banner
app.rental.end.require_parking_hint
app.wallet.show_minutes
app.support.chat_url
app.feature.new_vehicle_sheet_enabled

Use namespaced keys for app-specific settings. A good convention is to prefix custom app settings with app. and then the product area, such as app.rental.*, app.wallet.*, app.support.*, or app.feature.*.

Areas

The User API settings endpoint returns settings from app-relevant areas only:

Area Use
APP Mobile app and user web app settings. Use this for operator-created app configuration.
SHARED Settings intentionally shared across user-facing surfaces.

Dashboard-only and core-only settings are not exposed as normal user-app configuration. If an operator wants a setting to be available to a white-label app, create it in APP or, if appropriate, SHARED.

Branch Scope

Settings can be global defaults or branch-specific overrides. The response includes branchIds, and fallback values can be represented with branch ID 0.

Use branch-scoped settings when app behavior differs by operating branch, for example:

Common User App Workflow

Load Settings

Fetch settings by key:

GET /settings?keys=app.wallet.show_minutes&keys=app.support.chat_url

Fetch settings for specific branches:

GET /settings?keys=app.wallet.show_minutes&keys=app.support.chat_url&branchIds=3&branchIds=7

The endpoint returns an array of SettingSimple objects:

[
  {
    "key": "app.wallet.show_minutes",
    "area": "APP",
    "branchIds": [0],
    "value": {
      "enabled": true
    }
  },
  {
    "key": "app.support.chat_url",
    "area": "APP",
    "branchIds": [3],
    "value": {
      "url": "https://support.example.com/chat"
    }
  }
]

The value is an object. The app and operator must agree on the shape of each custom setting value.

Interpret Settings Safely

Treat settings as configuration, not as trusted client-side enforcement. Settings are good for UI behavior and feature decisions, but business-critical checks must still come from dedicated endpoints.

Recommended client behavior:

  1. Define the expected value shape for each key in app code.
  2. Validate the returned value before using it.
  3. Use app-bundled defaults when a key is missing.
  4. Prefer branch-specific values when they match the active branch.
  5. Fall back to global/default values when no branch-specific setting exists.
  6. Ignore unknown fields so operators can extend values later.

Example:

setting = findSetting("app.wallet.show_minutes", activeBranchId)
showMinutes = setting.value.enabled if boolean, else appDefault.showMinutes

Use Settings With Localization

Settings and localization work well together:

Example:

{
  "key": "app.wallet.empty_state",
  "value": {
    "enabled": true,
    "titleKey": "app.wallet.empty.title",
    "descriptionKey": "app.wallet.empty.description"
  }
}

The app then resolves titleKey and descriptionKey through GET /resources/messages?locale=....

Managing Settings

The User API reads settings. Operators manage settings through Operations API/admin settings management.

Management task API surface
Create a new app setting Operations settings management
Update setting value or type Operations settings management
Delete a setting Operations settings management
Read app settings in the customer app User API GET /settings

When adding custom app settings:

  1. Choose a stable key name.
  2. Put the setting in the APP area unless it is intentionally shared.
  3. Decide whether it is global or branch-specific.
  4. Define a small, stable JSON value shape.
  5. Document the expected fields for the app team.
  6. Add app defaults for missing or malformed values.

Avoid putting secrets, credentials, or enforcement-critical rules into app-readable settings. Anything returned by the User API can be inspected by the app user.

Most Relevant APIs

Area Endpoints
Read app settings GET /settings
Read localized text for setting-driven copy GET /resources/messages
List available localization languages GET /resources/messages/languages
Manage settings Operations settings management endpoints

Implementation Notes