Stackship platformUsers

User settings

The per-user settings the platform stores, their defaults, and the routes that read and change them.

The platform keeps a few settings for each signed-in person. They belong to the person, not to a boundary or a team, and nobody else can read or change them.

Settings and defaults

The settings are created, with these defaults, the first time any of the routes below is called for you:

Setting	Field	Default
Notifications on	`notifications.enabled`	`true`
E-mail notifications	`notifications.email`	`false`
Portal notifications	`notifications.portal`	`true`
Theme	`portalSettings.theme` — `dark`, `light` or `system`	`dark`
Language	`portalSettings.language`	`en-US`
Last "What's new" seen	`portalSettings.whatsNewSeenRelease` — a release name such as `platform-0.8.0`	none
Selected boundary	`selectedBoundary` — `id`, `name`, `region`	none

The notification preferences are stored, but nothing on the platform acts on them yet.

How the portal uses them

The portal's Settings page saves the theme and the language you choose. When the portal loads it reads back only the language, and applies it when it is en or sv. The theme the portal shows is remembered by the browser instead.

After the platform is upgraded, the portal shows the new release's What's new once. When you close it, the portal records that release in whatsNewSeenRelease, so it does not show it again until the next upgrade.

Routes

All routes act on the caller's own settings and need a signed-in caller, but no permission.

Method and path	Reads or replaces
`GET /user/settings`	All settings
`PUT /user/settings`	All settings: `notifications`, `portalSettings`, `selectedBoundary`
`GET` / `PUT /user/settings/notifications`	`enabled`, `email`, `portal`
`GET` / `PUT /user/settings/portal`	`theme`, `language`
`GET` / `PUT /user/settings/boundary`	`id`, `name`, `region`
`PUT /user/settings/whats-new`	`release`: the release whose "What's new" you have seen

In PUT /user/settings, leaving out notifications or portalSettings keeps their current values, but leaving out selectedBoundary clears it. The PUT routes never change whatsNewSeenRelease; only PUT /user/settings/whats-new does, and it refuses anything that is not a release name with 400. An unknown theme, or an empty language, is refused with 400; any other language value is stored as it is.

bash

stsh api GET /user/settings
stsh api PUT /user/settings/portal -d '{"theme":"light","language":"sv"}'