Replace the help centre's branding
Replace the help centre's branding object.
/v1/help-centre/brandAdmin- Operation id
- put_brand
- Access
- An editor or a viewer is refused.
/v1/help-centre/brandReplace the help centre's branding object.
This is a replace, not a merge. The object you send becomes the whole branding blob, so a key you leave out is removed.
The accepted keys are a closed set: a logo, a favicon, a colour, a title and a tagline, each of which the reader accepts under several spellings. A key outside that set is refused by name rather than quietly dropped, which is what stops a saved logo disappearing without explanation.
A URL must be an https:// address or a site-relative path. A colour must
be a hex value such as #0f1522. Anything else is refused, because the
reader would fall back to the neutral brand and leave an operator looking
at a help centre that ignored what they saved.
Each key is validated by what it means rather than how it is spelled, so all three spellings the reader accepts for a logo get the same allow-list. An omitted key is absent rather than null, which the read contract already tells every consumer to expect.
It is deliberately not permissive. This blob is served to every visitor of
a customer's public help centre and two of its fields land in src and
href, so an unvalidated spelling is stored XSS with a client-side guard
as its only defence.
Tenancy: the request is scoped to one workspace, and the credential presented is what selects it. A caller with no membership in that workspace is refused with 404, which is indistinguishable from a workspace that does not exist.
Authorisation: admin or owner. An editor or viewer receives 403 insufficient_role.
Access: Authorization: Bearer carrying either a realm access token or an API key. A key must hold the help-centre-staff:write scope, and the workspace role of the person who owns it must meet the floor above.
A realm-issued access token, presented as Authorization: Bearer <token>. It acts as the person who signed in, and every operation resolves their workspace role live from the membership record.
In: header
Query Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
help_centre.brand, replaced wholesale, and closed rather than free-form.
This blob is stored in JSONB and served to every visitor of a customer's
public help centre, and two of its fields end up in src and href. It
used to shape-check the five canonical keys and store any other key as sent,
which meant the aliases the reader accepts, logo, logoUrl and
favicon, were a validated field and an unvalidated one under two names. A
javascript: URL refused as logo_url was stored verbatim as logo and
read back by the same adapter.
So the accepted set is now closed and stated once, in BRAND_KEYS, and the
rule is chosen by what the key means: every asset key gets the asset rule,
every colour key the colour rule, every text key the text rule. There is one
implementation of each and no key without one.
An unrecognised key is refused, not dropped. Dropping is the worse failure of the two: the request succeeds, the response says the brand was saved, and the value is simply gone. For a form that reads back what it wrote, that looks like the customer's logo vanishing for no reason. A 422 that names the key is a thing an operator or an integrator can act on, and the closed set also bounds what the column can hold to eighteen short strings.
The five fields below are declared for the sake of the schema a client reads, and they are the spellings anything new should write. They carry no constraints of their own, because the constraint is the table above and a second copy on the field would be a second rule to keep in step.
Response Body
application/json
application/json
curl -X PUT "https://example.com/v1/help-centre/brand" \ -H "Content-Type: application/json" \ -d '{}'{ "help_centre_id": "string", "brand": {}}