Brand pack
A brand pack is a folder with a brand.json file and the image files it names. Mount the same folder into the Endatix API and Endatix Hub, turn on the WhiteLabeling feature flag, and the deployment uses your product name, logos, accent color, personas and links instead of the built-in Endatix brand. The same container images serve either brand, with no rebuild.
The pack is identity only: it says who the product is and where to reach it, not how email is sent. The email sender is set in the email settings. The pack is deployment-wide: every tenant sees the same brand.
Before you start
- Both apps read the pack. The API uses
name,links.websiteandlinks.supportin emails. The Hub uses the whole pack. Mount it into both, with the flag set to the same value in both. - The flag is off by default. With it off, a mounted pack is ignored and the built-in brand applies.
- Check the pack first with
pnpm brand:validate(see Validate a pack). With the flag on, an invalid pack stops the apps at start.
Write brand.json
Only version and name are required. In the Hub, a pack never falls back to Endatix's name or links: name stands in for legalName and the personas, and a link the pack leaves out is hidden. A file the pack leaves out keeps the built-in artwork.
{
"$schema": "https://docs.endatix.com/schemas/brand/1/brand.schema.json",
"version": 1,
"name": "Example Forms",
"legalName": "Example Ltd.",
"assets": {
"logo": { "light": "logo-light.svg", "dark": "logo-dark.svg" },
"icon": "icon.svg",
"ogImage": "og.jpg"
},
"tokens": {
"color": {
"primary": { "$type": "color", "$value": "#0b6b5d" },
"primary-on-dark": { "$type": "color", "$value": "#4fd1b8" }
}
},
"links": {
"website": "https://example.com",
"docs": "https://docs.example.com",
"support": "mailto:help@example.com"
},
"personas": { "assistant": "Example Assistant", "bot": "Example Bot" },
"poweredBy": false
}
The JSON Schema is published at https://docs.endatix.com/schemas/brand/1/brand.schema.json. Point $schema at it for completion and checks in your editor. The Hub rejects unknown keys.
Fields
Must be 1.
The product name, 1 to 60 characters. The Hub shows it in page titles (Sign in | Example Forms) and as the app name. The API fills {{productName}} with it, and it is the email sender name unless the email settings set one.
The company name, up to 120 characters. The Hub uses it as the page publisher in metadata. Defaults to name.
The logo, as { "light": "<file>", "dark": "<file>" }. light is required; dark is optional. Shown on the sign-in pages and in the expanded sidebar. Without it, the Hub keeps the Endatix wordmark.
The square icon: the browser tab icon and the collapsed sidebar. Without it, the Hub keeps the Endatix icon.
The social preview image for pages that have a description.
The accent color, as a design token { "$type": "color", "$value": "<color>" }. Hex, rgb(), hsl() or oklch(), up to 64 characters. The Hub derives its buttons, focus rings, sidebar ring and chart colors from it, for light and dark mode. Survey Creator follows. Text on the accent always gets at least 4.5:1 contrast.
The accent for dark mode, in the same format and with the same limit as primary. Without it, the dark accent is derived from primary.
The product website (http, https or mailto). The Hub links it from the sign-in pages. The API fills {{websiteUrl}} with it.
The documentation link in the Hub's help menu. Without it, the menu hides the entry.
The support link in the Hub's help menu. The API fills {{supportAddress}} from it only when it is a mailto: link to one address, for example mailto:help@example.com. See Support address.
The name of the AI assistant in the Hub. Defaults to "name AI Assistant".
The name of the Slack bot in the Hub. Defaults to "name Bot".
Shows (true) or hides (false) the "Powered by" line at the foot of public status pages, including those of /share and /embed. It wins over the Hub's ENDATIX_SHOW_POWERED_BY; left out, that variable decides.
The schema also accepts links.privacy and links.terms. They are validated, but the Hub does not show them yet.
The sender address and name are not brand fields. Set them in Endatix:Integrations:Email:Sender (see Email settings). The API ignores an email section left in an older pack, and the Hub still accepts one.
Files
- Every file
brand.jsonnames must exist in the folder. - Paths are relative to the pack folder. Each segment uses only letters, digits,
.,_and-, does not start with., and no path contains... - Without
assets.logo.dark, dark mode uses thelightfile. - File types:
.svg,.png,.jpg,.jpeg,.webpor.ico. - The Hub serves only the files
brand.jsonnames, without sign-in, under/brand/<file>.
Validate a pack
From an Endatix Hub checkout, after pnpm install:
pnpm brand:validate ./brand
It runs the same checks the Hub runs at start. On success it prints Brand pack OK: <name> (<folder>, <n> files) and exits 0. On failure it prints each problem with its field path and exits 1. It also warns when an accent color has less than 3:1 contrast against the light or dark page background (WCAG 2.x); the pack still applies.
The API checks a few more rules at start, so a pack can pass brand:validate and still stop the API: no blank or whitespace-only name, links.website, links.support or personas.assistant, no control characters in name, and a mailto: support link to one bare address (mailto:help@example.com, not mailto:Example <help@example.com>).
Deploy with Helm
Both Helm charts take the same two values: whiteLabeling.enabled for the flag and brandPack for the mount. Set them to the same values in the API release and the Hub release.
-
Create a ConfigMap from the pack folder, in the namespace of both releases:
kubectl create configmap brand-pack --from-file=./brand -
Set the values in both charts:
values.yamlwhiteLabeling:enabled: truebrandPack:configMap: brand-packmountPath: /etc/endatix/brand -
Upgrade both releases. The charts mount the ConfigMap read-only at
mountPathand setENDATIX_BRAND_DIRto it.
A ConfigMap holds at most 1 MiB, and its keys cannot contain /, so keep the files flat and small. For subfolders or larger images, use a volume:
- Hub chart: set
brandPack.volumeto a volume source, for example{ persistentVolumeClaim: { claimName: brand-pack } }, instead ofconfigMap. Setting both fails the install withSet brandPack.configMap or brandPack.volume, not both. - API chart: it has no
brandPack.volume. Mount the volume withextraVolumesandextraVolumeMounts, and setENDATIX_BRAND_DIRwithextraEnv.
Without Helm
Mount the folder into each container and set:
The pack folder, holding brand.json. Both the API and the Hub read it. Unset means the built-in brand.
true turns on the WhiteLabeling flag in the API.
true turns on the white-labeling flag in the Hub with environment flags. With PostHog flags (FLAG_PROVIDER=posthog and a project token), the Hub reads white-labeling from PostHog instead. See Hub feature flags.
The API reads its flag only from configuration. When the Hub uses PostHog flags, keep the PostHog white-labeling flag and whiteLabeling.enabled in step, or the Hub and the emails show different brands.
What happens at start
API. With the flag on and ENDATIX_BRAND_DIR set, the API reads brand.json once at start. It checks the fields it uses and refuses to start on an invalid pack, naming every failing field:
Brand pack file '/etc/endatix/brand/brand.json' is not valid: /version: must be 1; /links/support: must be a mailto link to one email address
A missing file fails with Brand pack file '<path>' was not found. Set ENDATIX_BRAND_DIR to a folder that holds brand.json. With the flag off, the API does not read the pack. With the flag on and ENDATIX_BRAND_DIR unset, the API uses the built-in brand without an error. A change to the pack needs an API restart.
Hub. With the flag on, an invalid pack stops the Hub at start with the field paths in the error. With environment flags and FLAG_WHITE_LABELING not true, the problem is only logged and the Hub starts. Under PostHog flags the flag is decided per request, so an invalid pack always stops the Hub: turning the flag off in PostHog does not help. Fix the pack or remove the mount.
While running, the Hub reads the pack again when the folder, brand.json or a file it names changes. A change that does not validate is logged, and the last valid brand.json keeps serving.
Emails
Template variables
Every email the API sends can use three variables, filled from the brand. A stored template renders them; a provider template (a SendGrid or Mailgun template id) receives them as dynamic data.
| Variable | Value with a pack | Built-in value |
|---|---|---|
{{productName}} | name | Endatix |
{{supportAddress}} | the address in a mailto: links.support | support@endatix.com |
{{websiteUrl}} | links.website | https://endatix.com |
Metadata an email sends with the same key wins over the brand value. A pack that leaves out links.website keeps https://endatix.com in emails, and a pack that leaves out links.support keeps support@endatix.com, with no warning.
The seeded templates do not use these variables yet: their subjects and bodies still say Endatix. The text the API composes into the verification and invitation emails already uses the pack's name.
Support address
{{supportAddress}} takes the address from links.support only when the link is mailto: with one address. A web link (https://...) or a list of addresses (mailto:a@example.com,b@example.com) keeps support@endatix.com, and the API logs warning 6003 at start:
Brand pack: /links/support is not a mailto link, so emails use the built-in support address
A list logs Brand pack: /links/support names more than one address, so emails use the built-in support address.
Sender
The pack does not set the sender. The From address and name come from the deployment sender, Endatix:Integrations:Email:Sender:Address and Sender:Name:
- Address: the per-template
Endatix:EmailTemplates:<Template>:FromAddress, thenSender:Address, then the address on the template row. - Name: a display name written in the per-template
FromAddress(Ops Team <ops@example.com>), thenSender:Name, then the brand'sname.
The deprecated Endatix:Integrations:Email:SmtpSettings:DefaultFromName is still read as the name below Sender:Name, before the brand's name. The deprecated DefaultFromAddress is not part of the address order above: it sends only an email with no template and no From address, and never replaces a template row's address. Either one logs warning 6002 at start. See Email settings.
Limitations
- Respondent pages (
/shareand/embed) keep the built-in look. Only their page title and the "Powered by" line follow the pack. - Webhook headers keep the
X-Endatix-prefix. - Seeded email copy still names Endatix until you edit the templates.
- One brand per deployment. Tenants cannot set their own brand.