API Branding & White-Label Guide

00 Who this is for

This page covers the partner branding / white-label subsystem. Read the panel walkthrough whichever hat you wear; the endpoint chips and the reference at the end are there when you need to wire it up.

What a white-label partner is

A white-label partner is a Lightning Payroll account that has been granted API-admin access. That account owns an OAuth client and a single branding record, and its customers experience a branded version of Lightning Payroll. The flagship example is Farm Focus, the reseller these paths were first built for.

Provisioning the account and OAuth client is covered in the API Admin Setup guide; this page picks up at the branding record and the screen that edits it.

01 How branding resolves

Most API-admin responses carry two branding objects. Knowing which is which saves a lot of “why isn’t my logo showing” debugging.

effective_branding.source_type tells you where the resolved branding came from:

02 The Branding panel

Everything below lives on one screen: Manage API Client → Branding. It is a single Whitelabel Branding card plus a live email preview and, once configured, a branded-login card. Here is the whole panel, then each control in turn.

/admin/manage-api · Branding

Email header preview

A live, approximate render of how the branded email header will look with the current assets.

The preview updates as you upload, so a designer can see the “banner replaces logo and name” effect without sending a test email. It renders the same branch logic the real email uses (see How branded email renders).

The preview is approximate: it shows the light-mode header and does not reflect the email accent colour or dark-mode logo switching. The authoritative render is always the sent email.

Custom stylesheet

Optional CSS to theme the authenticated app: colours, typography, and layout details across the admin shell.

Optional

Upload a UTF-8 .css file up to 64 KB; changes apply immediately. Include body.lp-dark-mode rules for dark-mode support. The panel calls out the recommended theming hooks — --lp-branding-header-text, --lp-branding-muted-text, --lp-branding-action-text, --lp-branding-nav-text, and the --lp-table-* family for data tables.

CSS Generator Help

The CSS Generator Help button opens a modal with a browser-console command that generates a first-pass whitelabel CSS file from a reference app, copies it to your clipboard, and downloads generated-whitelabel.css. It is a strong starting point, not a final theme — expect to tweak navbar contrast, dark mode, and one-off components.

GET·POST·DEL/api/api-client/whitelabel-style

Branded login URL

A copyable link that opens the login page pre-branded for this partner.

This card appears once a public branding token exists. The link looks like:

https://app.lightningpayroll.com.au/auth/login?branding_token=<public-branding-token>

Opening it renders the standard login page pre-branded (logo, name, colours), resolved from the public branding token. Share it as the partner’s “log in here” link.

Edit branding details

The modal behind “App Branding Text”: display name, subtitle, support contacts, links, and theme options.

The modal groups the text and link fields that make up the brand identity:

Field	What it drives
Brand display name	The name in the admin header/sidebar and the email heading.
Brand subtitle	Tagline; also drives the “Powered by Lightning Payroll” attribution line.
Support email / phone	Shown on branded login, reset-password, and support prompts.
Homepage URL	Replaces Lightning Payroll links in navigation and emails.
Support / FAQ URL	Replaces LP support links in emails and navigation.
Lock to light mode	Prevents users switching to dark mode — use when your stylesheet has no dark rules.

Brand text fields are saved through the API-admin update endpoint, not a per-asset upload:

POST/api/update-api-client

03 Asset specifications

Every value here is enforced by the backend; an upload that violates it is rejected with a 400. Two odd-ones-out are worth remembering: only the favicon accepts .ico, and only the email banner has a 2 MB ceiling.

04 How branded email renders

The email header renders in one of three states. This is exactly what the in-panel Email Header Preview mirrors.

1. Banner set → the banner image, full-width. No logo, no brand-name heading.
2. No banner, logo(s) set → the logo (light + dark pair, or a single logo), then the brand name as a heading, then the optional subtitle.
3. No branding identity at all → the default Lightning Payroll header.

The banner is served to the email as an <img src> from the public serve endpoint (below). It scales down only to fit, never up, and degrades safely: if the banner bytes or the branding token are missing, the header quietly falls back to the logo/heading branch, so a misconfigured banner never breaks an email.

05 Endpoint reference

The management endpoints below are gated by API-admin auth — a normal Lightning Payroll bearer token for the partner’s own account, not OAuth client credentials. The public serve/resolve endpoints are unauthenticated and resolve by client_id or branding_token.

Asset upload semantics

POST handlers are multipart/form-data with a file field and an overwrite_existing boolean (default false). Error semantics are consistent across the asset endpoints:

Example — email banner CRUD

# Read banner metadata
curl -sS "$BASE_URL/api/api-client/whitelabel-banner" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

# Upload (first time)
curl -sS "$BASE_URL/api/api-client/whitelabel-banner" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "file=@partner-banner.png"

# Replace an existing banner
curl -sS "$BASE_URL/api/api-client/whitelabel-banner" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -F "overwrite_existing=true" \
  -F "file=@partner-banner.png"

# Delete
curl -sS -X DELETE "$BASE_URL/api/api-client/whitelabel-banner" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Serving an asset publicly

The unauthenticated serve endpoint returns image bytes; the mode query parameter selects which asset. mode=banner is what a branded email embeds as its banner image source.

curl -sS "$BASE_URL/api/public-branding/logo?branding_token=<token>&mode=banner" \
  --output banner.bin

Other modes fall back favicon → dark → primary logo.

06 Related guides