Skip to main content
The User Settings service stores user preferences and sidebar navigation state server-side, enabling cross-device synchronization. It is served by the Organizations & Metrics microservice at REACT_APP_ORGANIZATIONS_API_BASE_URL (default: https://api.makakoo.com/ma-metrics-wsp-ms/v1/api). All requests require Api-Key and Authorization: Bearer <token> headers.

​
Get User Settings

GET /user_settings
Return the authenticated user’s settings, including the sidebar data structure used to render navigation. A single call to this endpoint can replace multiple separate API calls at login time.
​
client
string
Client identifier. Use "web" for browser clients. Defaults to "web".
​
includes
string
Comma-separated additional data to include. Pass "dashboard" to include dashboard cache data alongside sidebar data.
curl "https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/user_settings?client=web" \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>"
​
sidebar
object
Sidebar navigation data. Ready for direct rendering — no transformation required.
​
current_organization_id
integer | string
The user’s last-selected organization ID, synced across devices.
​
current_project_id
integer | string
The user’s last-selected project ID, synced across devices.
​
language
string
The user’s preferred language code (e.g., "en").
​
theme
string
The user’s preferred theme: "light" or "dark".
​
sidebar_open
boolean
Whether the sidebar is open.
​
dashboard
object
Dashboard cache data (only present when includes=dashboard).
Example sidebar response: 
{
  "sidebar": {
    "organizations": [
      {
        "id": 123,
        "name": "Makakoo",
        "currentUserRole": "ADMIN",
        "meta": {
          "can": {
            "organization": { "manageSettings": true },
            "project": { "create": true }
          }
        },
        "pinned_items": [
          { "type": "project", "id": 1, "name": "sleepbananas", "position": 0 }
        ],
        "projects": [
          { "id": 1, "name": "sleepbananas", "is_default": true },
          { "id": 2, "name": "My First Project", "is_default": false }
        ]
      }
    ]
  },
  "current_organization_id": 123,
  "current_project_id": 1,
  "language": "en",
  "theme": "light",
  "sidebar_open": true
}

​
Update User Settings

PATCH /user_settings
Update one or more settings for the authenticated user. Changes are synced immediately to the server; the client also updates localStorage so the UI reflects the change without waiting for the API response.
​
client
string
Client identifier. Defaults to "web".
​
theme
string
User’s preferred theme: "light" or "dark".
​
language
string
User’s preferred language code (e.g., "en", "es").
​
sidebar_open
boolean
Whether the sidebar should be open.
​
current_organization_id
integer | string
The ID of the currently active organization. Accepts both integer and UUID formats.
​
current_project_id
integer | string
The ID of the currently active project.
curl -X PATCH "https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/user_settings?client=web" \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "theme": "dark",
    "current_organization_id": 123,
    "current_project_id": 1
  }'
Response: 200 OK.
To avoid excessive API calls when the user changes settings rapidly, the client debounces calls to this endpoint with a 500ms delay. Build the same behaviour into custom integrations.

​
Update Pinned Projects

PATCH /user_settings
Update the list of pinned projects for a specific organization. Pinned projects are shared across all clients (devices) for the same user.
​
client
string
Client identifier. Defaults to "web".
​
setting_key
string
required
Must be "sidebar".
​
organization_id
integer
required
The organization ID whose pinned projects you are updating.
​
pinned_project_ids
array
required
Ordered array of project IDs (integers) to pin. The position in the array determines display order.
curl -X PATCH "https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/user_settings?client=web" \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "setting_key": "sidebar",
    "organization_id": 123,
    "pinned_project_ids": [1, 5, 12]
  }'

​
Mark Onboarding Step

PATCH /user_settings/onboarding/{stepId}
Record completion of an onboarding step or update its state.
​
stepId
string
required
The onboarding step identifier, e.g., "sentinel_pass_discovered" or "is_hidden".
​
client
string
Client identifier. Defaults to "web".
​
value
any
The value to set for the step. Defaults to true.
curl -X PATCH "https://api.makakoo.com/ma-metrics-wsp-ms/v1/api/user_settings/onboarding/sentinel_pass_discovered?client=web" \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"value": true}'
Response: 200 OK on success, false return value from the service on error (non-throwing).

​
Cross-Device Sync Behaviour

User settings follow a local-first strategy:
  1. On login, call GET /user_settings?client=web to load the latest settings and sidebar data from the server.
  2. Write settings to localStorage immediately for fast local reads.
  3. When a setting changes, update localStorage first, then call PATCH /user_settings in the background.
  4. API call failures are logged as warnings and do not affect the local state. The client continues to function using localStorage when the API is unavailable.
  5. Debounce rapid setting changes at 500ms to avoid excessive API traffic.

​
ID Validation

Organization and project IDs are validated before being sent to the API:
  • UUID format (8-4-4-4-12 hex characters): sent as a string.
  • Numeric format: parsed as an integer.
  • Invalid or empty values: converted to null and omitted from the payload.

Build docs developers (and LLMs) love

Get started for freeTalk to us