Skip to content
Dashboard
Theme
Theme

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.

View Markdown

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.

  • POST /v1/branding/favicon: a square PNG from 16 to 512 pixels.
  • POST /v1/branding/font: a single WOFF2 file of at most 512 KiB, checked against its own table directory; an invalid file answers font_invalid.
  • surfaces in PATCH /v1/branding holds separate sets for portal, consent and email. 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 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_name variable 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.

A logo is a two-step change: upload the file, then point the branding at it.

  1. Send the file base64-encoded (standard alphabet, with padding) as data to POST /v1/branding/logo. The response carries logo_url, content_type, width, height and size_bytes. Uploading does not change the branding.
  2. Set that URL with PATCH /v1/branding and {"logo_url": "<logo_url>"}. Only a URL returned by the upload call for the same environment is accepted; any other URL answers parameter_invalid. Send null or "" 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.

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 viewBox of 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 or data: 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.

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, foreground and accent of each of light and dark, as hex (#rgb or #rrggbb). accent colors buttons, links and the focus ring; when it is unset, primary is used instead. The page picks black or white button text, whichever contrasts more with the accent.
  • Font: system, serif or mono. Any other font value is stored but the consent screen shows the system font.
  • Radius: 0 to 16 pixels. A larger stored value is shown as 16.

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.

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.