Branding
Set the portal and consent screen colors, logo, font, radius and app name, the contrast rule, and the upload rules for PNG and SVG logos.
Branding is environment-scoped and set through the management API with a secret key: read it with GET /v1/branding (branding:read) and change it with PATCH /v1/branding (branding:write). An absent field is kept; an explicit null (or "" for a string) clears it.
Branding styles two hosted pages: the setup portal and the consent screen your users see during sign-in. The portal themes the primary color of each of light and dark only and always uses its own neutral surfaces and text; it ignores background and foreground. It renders corner radius at no more than 12 pixels.
Branding is a Pro feature. Below Pro (sandboxes included), PATCH /v1/branding and the uploads answer plan_limit_reached, and the hosted pages show the default OhAuthCat branding even when settings were saved earlier. Organizations can override the logo and primary color on Pro and above; the setup portal and the consent screen use the organization’s values when the sign-in or link names that organization.
Favicon, font and per-surface sets
Section titled “Favicon, font and per-surface sets”POST /: a square PNG from 16 to 512 pixels.v1/ branding/ favicon POST /v1/branding/font: a single WOFF2 file of at most 512 KiB, checked against its own table directory; an invalid file answersfont_invalid.surfacesinPATCH /v1/brandingholds separate sets forportal,consentandemail. Each field falls back to the main set when a surface does not set it;{}removes the surface sets.
Fonts and favicons are served from the OhAuthCat assets origin, and the consent screen’s Content Security Policy allows fonts from that origin only when a font is set. See email branding for what emails use.
App name
Section titled “App name”app_name names your application to your customers’ IT admins. It is 1 to 100 characters without control characters; send null or "" to clear it.
- Portal invites: the invite email says that your app invited the admin, and the subject names it.
- IT-admin emails: it is the
application_namevariable of the customer IT email templates, such as setup invitations and reminders.
Until you set it, invites use the generic name “Your software provider” and a subject that names no app.
Upload a logo
Section titled “Upload a logo”A logo is a two-step change: upload the file, then point the branding at it.
- Send the file base64-encoded (standard alphabet, with padding) as
datatoPOST /v1/branding/logo. The response carrieslogo_url,content_type,width,heightandsize_bytes. Uploading does not change the branding. - Set that URL with
PATCH /v1/brandingand{"logo_url": "<logo_url>. Only a URL returned by the upload call for the same environment is accepted; any other URL answers"} parameter_invalid. Sendnullor""to remove the logo.
The same file always gets the same URL, so retrying an upload is safe. Logos of the environment that are not the current logo_url are removed after an hour.
Logo file rules
Section titled “Logo file rules”The file type is read from its bytes, never from a file name or header.
Every logo is at most 256 KiB, both as uploaded and after we normalize it.
- PNG: 16 to 2048 pixels per side. We decode it and re-encode it without its metadata chunks.
- SVG: an SVG root with a
viewBoxof at most 2048 units. We rebuild it from a safe subset: shapes, groups, gradients and clip paths with presentation attributes. Scripts, styles, event handlers, text, images, links and every external ordata:reference are removed.
Anything else answers logo_invalid; its message names the problem. Convert text in an SVG logo to paths before uploading, because text elements are removed.
Consent screen
Section titled “Consent screen”The hosted consent screen uses more of the branding than the portal does.
- Logo: only the logo you uploaded. The page loads images from the assets host and nowhere else.
- Colors:
background,foregroundandaccentof each oflightanddark, as hex (#rgbor#rrggbb).accentcolors buttons, links and the focus ring; when it is unset,primaryis used instead. The page picks black or white button text, whichever contrasts more with the accent. - Font:
system,seriformono. Any otherfontvalue is stored but the consent screen shows the system font. - Radius: 0 to 16 pixels. A larger stored value is shown as 16.
Contrast rule
Section titled “Contrast rule”Each theme must keep text readable: foreground and the accent each need a contrast of at least 4.5:1 (WCAG AA for body text) on that theme’s background, or on the default background when you leave it unset. Otherwise PATCH /v1/branding answers parameter_invalid and its param names the failing field, such as light.foreground or dark.accent. When only the background changed, the field named is the background.
Defaults
Section titled “Defaults”Any color you leave unset uses the product default:
| Token | Light | Dark |
|---|---|---|
background |
#ffffff |
#15152a |
foreground |
#15152b |
#ededfb |
accent |
#c94820 |
#f08a5d |
Setting foreground also makes secondary text that color, and setting foreground or background draws borders in the secondary text color. Secondary text needs 4.5:1 on the background as well; when it falls short, the error names the background.
See portal links and custom domain limits. Portal links use your verified custom portal hostname when you have one.