Your display identity
The display-identity block is what the platform-rendered surfaces — the patient portal, the hosted checkout door, and the sign-in screen — read to wear your brand instead of the default. It carries four things and nothing else:
The brand you are writing is resolved from your key context, never from the request body. You
present the brand in the
X-Brand-Id header, and the brand_id in the path must match it. A brand
your key does not own — foreign, unknown, or mismatched — answers 404, never 403: there is no
way to probe whether another tenant’s brand exists.
Set it with your key
Send the display block toPUT /v1/account/brands/{brand_id}/config. The body carries a single
display object; that is the only field read here.
- The version is server-minted. You never send
version; the platform mints a new monotone version on each write and returns it — so every write, including a repeat, advances the version. The stored write is durable before it takes effect, so a restart re-serves exactly what you last wrote. - The block is merged, not replaced wholesale. Your display block is merged onto the existing configuration, so a display write never disturbs the platform-managed redirect allowlist or theme.
Read it back
GET /v1/account/brands/{brand_id}/config returns the configuration as the platform holds it — the
readback promised in your welcome kit. It is key-scoped the same way: the path brand_id must match
your X-Brand-Id, and any other brand answers 404. A brand with no configuration set yet also
answers 404.
Where it renders
You do not call anything to make the display identity show up. The platform-rendered surfaces resolve it per request from your brand context and wear it automatically: the patient portal, the hosted checkout door, and the sign-in screen. A brand that has no display block does not error — those surfaces fall back to the platform’s default look, and the fallback is always explicit: the default is never silently presented as your brand’s own identity.The token reference
tokens is a partial theme set. You supply any subset of the slots below; anything you omit
falls back to the platform default when the theme is assembled. Every leaf value is a string. An
unknown group, mode, or slot is refused (see the wording wall).
tokens accepts three groups:
Within
colors.light and colors.dark, the slot names are the semantic color slots of the
platform design-system brand-token contract. They are the exact vocabulary the theme stylesheet is
generated from, so they can never drift from what the surfaces actually render. Grouped by the
surface each one themes:
Partial override. You may set as few as one slot in one mode. The write is merged onto your
existing configuration and, at render time, onto the platform default — so a single-slot write
re-themes only that slot and leaves the rest of your look intact.
Unknown slots are refused. A slot name outside the vocabulary above (a typo, or a slot the
platform does not define) fails the whole write with
422 and a slot-level issue — nothing is
stored. A color value must be a non-empty string; an empty or non-string value is refused the same
way.
The wording wall
The display block is theming only — name, logo, and tokens. It is not a copy channel and can never carry patient-facing wording. Acopy key inside display is refused outright with 422:
display_name,
logo, tokens, and support_email is refused the same way with brand.display.unknown_key.
The client write reads only the display block. Anything else you place in the body — a theme,
a redirect allowlist, a brand id, a charge setting — has no effect here: those stay
platform-managed and cannot be set through your key.
The operator override
The same display block can also be written from the platform’s operator surface, as an override or as a starting look seeded when your brand is first created. That is a platform-side path, not yours; it writes the one shared configuration your readback returns, and it runs through the identical validator and the same wording wall. From your side there is one display identity, whichever path last wrote it — and the readback always shows you exactly what is stored.The rest of your configuration
Everything else in your brand configuration is platform-managed — set through your onboarding contact and confirmed through the same readback. Each member has a fixed meaning:theme— the presentation overlay for the intake questionnaire: theme tokens the renderer applies to each already-sequenced question. It is a separate token system from your display identity. The displaytokensabove dress the platform-rendered surfaces (portal, checkout, sign-in);themedresses the questionnaire your own renderer draws. The two are disjoint — the same brand may set both, and neither overrides the other. See how intake serving works.copy— brand copy slots for your non-clinical surfaces, keyed by slot. A copy slot changes wording on those surfaces only; it can never supply or override a question’s headline, which comes from the reviewed questionnaire. (This is separate from the display block, which carries no copy at all.)enabled_therapies— references to the therapies your brand offers. References, never definitions: the therapy, its questionnaire, and its clinical rules live on the platform.commercial— identifiers tying the brand to its storefront and pricing. References only.redirect_allowlist— the absolutehttpsURL prefixes a patient may be returned to after completion. Matching is exact origin plus path prefix; an entry that matches nothing is dropped, and an empty list refuses every redirect. Fail-closed by design — an open redirect is unrepresentable.
The clinical wall
The whole brand configuration — display identity included — is clinically inert by construction. Two checks run on every write, before anything is stored:- A closed allowlist. A configuration, and the display block within it, may carry only their permitted keys. Any other key is rejected.
- A clinical-shape scan. The entire configuration is scanned at every depth for any key that could carry clinical meaning — facts, options, controls, rules, sequencing, visibility, and their relatives. One such key anywhere fails the whole write.