# Branding

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](#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.

## Plans

Branding is a Pro feature. Below Pro (sandboxes included), `PATCH /v1/branding` and the uploads answer [`plan_limit_reached`](/errors/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

- `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`](/errors/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](/hosted-portal/email-branding/) for what emails use.

## 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_name` variable of the [customer IT email templates](/hosted-portal/customer-it-email/), 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 id="logo-upload"></a>

## Upload a logo

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`](/errors/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.

<a id="logo-rules"></a>

## 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 `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`](/errors/logo_invalid/); its `message` names the problem. Convert text in an SVG logo to paths before uploading, because text elements are removed.

<a id="consent-screen"></a>

## Consent screen

The hosted consent screen uses more of the branding than the portal does.

- **Logo:** only the logo you [uploaded](#logo-upload). 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.

### 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`](/errors/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

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](/hosted-portal/portal-links/) and [custom domain limits](/sso/custom-domains/). Portal links use your verified custom portal hostname when you have one.
