---
title: "Update workspace preferences"
method: PATCH
path: "/v1/account/prefs"
tags: ["account"]
---

# Update workspace preferences

`PATCH /v1/account/prefs`

## Request

- Base URL: `https://api.brixsignage.com`
- URL: `https://api.brixsignage.com/v1/account/prefs`
- Auth: HTTP bearer

Updates workspace-level preferences such as locale, time zone, date and number formats, brand kit, and plan tier. Any field you include is overwritten; fields you omit keep their current value.

## Request body

- object: Any `WorkspacePrefs` keys to change; omitted keys keep their value. `supportAccess`, `retention`, `warehouse` and the PIN hash are ignored here (they have their own routes, or are set by Brix).
  - `kioskPin` string, nullable: Set (4–8 digits) or clear (null) the workspace Screen Lock PIN. Stored as a hash.
  - `requireSso` boolean: Needs a working single sign-on connection with verified domains; until someone signs in through it, the request is held (`requireSsoPending`).
  - `requireTwoFactor` boolean: Turning it on needs the calling user to have two-factor sign-in set up, so an API key cannot turn it on.

## Response `200`

Success.

- object
  - `data` WorkspacePrefs, required: Workspace preferences. Every key is present (defaults filled in).
    - `timeFormat` '12h' | '24h', required
    - `weekStart` 'mon' | 'sun', required
    - `dateFormat` 'mdy' | 'dmy' | 'ymd', required
    - `tempUnits` 'f' | 'c', required
    - `timeZone` string, required: IANA time zone. Screens without their own zone use it, and so do schedules timed by the workspace.
    - `language` string, required: BCP 47 language tag.
    - `multinational` boolean, required: Shows the per-location and per-screen language settings.
    - `newLocationsPayFirst` boolean, required: New locations pay for themselves before going live: each adds its own card, and its screens show a hold card (not billed to the account) until then. Default false. Turning it on needs Brix billing with a running plan (409 otherwise).
    - `navExtras` string[], required: Console pages switched on that the workspace size hides by default.
    - `appBranding` object, required: The look of the on-screen apps.
      - `accent` string, required
      - `accent2` string, required
      - `theme` 'dark' | 'light', required
      - `backdrop` 'brand' | 'wash' | 'plain' | 'aurora' | 'dots' | 'grid' | 'solid', required
      - `intensity` number, required
    - `audio` object, required: Default screen volume and a master mute.
      - `volume` number, required: 0–100.
      - `muted` boolean, required
    - `brand` object, required
      - `companyName` string, required
      - `logoUrl` string, required
    - `requireAltText` boolean, required
    - `showScreenLogo` boolean, required
    - `keepTvOnInput` boolean, required: Default for "Keep the TV on this input" on screens that have not set their own.
    - `standbyContentKind` string, nullable, required: What a screen with nothing to play shows; null = the default card.
    - `standbyContentId` string, nullable, required
    - `tier` 'simple' | 'team' | 'enterprise', required: Workspace size. It sets console defaults, not access.
    - `industry` string, nullable, required
    - `onboardingCompletedAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `setupStep` string, nullable, required: Walkthrough position (`s1`…`s5`, `l1`…`l6`, `done`).
    - `welcomeDeclinedAt` string, nullable, required: ISO-8601 timestamp (UTC).
    - `aboutYouDue` boolean: The workspace is asked the first-sign-in questions (workspaces created from 2026-10-14).
    - `aboutYouAt` string, nullable: ISO-8601 timestamp (UTC).
    - `expectedScreens` integer, nullable: How many screens the owner said they expect.
    - `orgNameSet` boolean, required
    - `tiers` integer[], required: Location tree levels in use.
    - `tierLabels` object, required: Custom names for the location tree levels.
    - `requireTwoFactor` boolean, required
    - `requireSso` boolean, required
    - `requireSsoPending` boolean, required: Single sign-on was required, and turns on after the first sign-in through the connection.
    - `requireSsoPendingSince` string, nullable, required: ISO-8601 timestamp (UTC).
    - `ai` object, required
      - `enabled` boolean, required
      - `features` object, required: Per feature (`tags`, `alt-text`, `moderation`, `transcription`, `translation`, `focal-region`, `embedding`); an absent feature follows `enabled`.
      - `dailyCallLimit` integer, nullable, required
      - `redactPersonalData` boolean, required
    - `retention` object, required: Days kept per stream, only for the streams the workspace has set. An absent stream uses the platform window.
      - `offline` number
      - `screenshots` number
      - `playback` number
      - `deviceLogs` number
      - `vitals` number
      - `replays` number
      - `aiEvents` number
    - `warehouse` object, required: Data warehouse feed. Set by Brix; not writable here.
      - `enabled` boolean, required
      - `bucketBinding` string, required: Set by Brix when the data warehouse feed is provisioned.
      - `tables` string[], required
      - `lookbackDays` integer, required
    - `supportAccess` SupportAccessPolicy, required
      - `mode` 'open' | 'notify' | 'approve', required: `open`: Brix support may open the workspace. `notify`: it may, and the owners are emailed. `approve`: a person here must approve each request.
      - `grantMinutes` integer, required: How long an approval lasts.
      - `requestTtlMinutes` integer, required: How long a request waits for an answer before it expires.
    - `kioskHasGlobalPin` boolean, required: A workspace Screen Lock PIN is set. The PIN and its hash are never returned.

## Other responses

- `401`: Missing, expired or revoked bearer token.
- `403`: You do not hold the permission for the whole workspace (a grant at one location is not enough).
- `422`: `sso_not_configured`, `two_factor_not_enrolled`, or a PIN that is not 4–8 digits.
- `5XX`: Server error. The body carries a `requestId` to quote to support.

---

[API](https://skmtc.dev/brixsignage/apis/brix-api.md) · [All operations](https://skmtc.dev/brixsignage/apis/brix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/brixsignage/apis/brix-api/revisions/02fd3665dc7d?raw)