---
title: Branding
project: Authaz
updated: 2026-04-29T17:34:56.250Z
---


# Branding

The **Branding** tab is where Universal Login picks up your visual identity. Logo, colors, font, button shape, background, dark-mode treatment — saved here, applied instantly on the next sign-in, no redeploy. The same branding propagates to your transactional emails (welcome, magic link, invitation, password reset) automatically.

The page is split into a **light mode** column and a **dark mode** column with a live preview alongside. There's also an **Appearance** strip for fonts, radii, and layout.

## Where it lives

**Dashboard → Application → Branding.** The page header reads *Branding* with a subtitle that depends on context — "Manage the shared application branding" by default, or "Branding for *Tenant Name*" when you're editing a per-tenant override.

## Theme presets

Before you customize anything, pick a preset. The dashboard ships a curated set across categories (Minimal, Bold, Soft, Dark-first, Brand-forward) — they're starting points you then tweak. Selecting a preset overwrites your current settings (after a confirm dialog).

Once your settings stop matching any preset, the editor shows "Custom" as the active selection.

## Light mode + dark mode

Each mode has its own palette. The user's browser/OS picks which they see, or you can force one via the **Theme mode** setting (see Appearance below).

Per-mode controls:

| Setting | What it controls |
|---------|-----------------|
| **Logo** | Full-width logo shown above the form. PNG/SVG, recommended ~240 px wide. |
| **Logo icon** | Square favicon-sized variant for tight layouts. |
| **Favicon** | Shown in the browser tab on Universal Login pages. |
| **Page background** | The color behind everything. |
| **Button background** | Primary CTA color (Sign in, Sign up). |
| **Button text** | Foreground color of the primary CTA. |
| **Links** | Color for hyperlinks (forgot password, terms, etc.). |
| **Background image** | Optional. URL of an image overlaid on the page background. |
| **Background image opacity** | 0.0–1.0. Controls how much of the page background bleeds through. |
| **Background image position** | `center`, `top`, `bottom`, etc. — standard CSS values. |

## Appearance

These apply to both modes:

| Setting | What it controls |
|---------|-----------------|
| **Font family** | Any Google Font name. The dashboard loads the font dynamically for the preview. |
| **Border radius** | `None`, `Small`, `Medium`, `Large`, `Pill`. Applied to inputs and buttons. |
| **Card shadow** | `None`, `Small`, `Medium`, `Large`. Drop shadow under the login card. |
| **Card border** | `None`, `Subtle`, `Solid`. Stroke around the login card. |
| **Theme mode** | `light`, `dark`, or `auto` (follows the user's OS preference). |
| **Layout variant** | `centered` (default — login card centered on page). More variants ship over time. |

## Live preview

The right side of the page shows a real Universal Login surface rendered with your current settings. Toggle between:

- **Mode** — Light or Dark, lets you tune both palettes in one session.
- **Viewport** — Desktop or Mobile.
- **Screen** — Login, Sign up, Reset password, MFA, Tenant picker, etc. Click through to make sure your styling holds across every flow.

Saving is explicit — the editor tracks unsaved changes and warns if you try to navigate away.

## API equivalent

```bash
curl -X PUT https://your-app.authaz.io/api/v1/applications/{appId}/branding \
  -H "X-API-Key: $AUTHAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "appearance": {
      "fontFamily": "Inter",
      "borderRadius": "Medium",
      "cardShadow": "Large",
      "cardBorder": "None",
      "themeMode": "light",
      "layoutVariant": "centered"
    },
    "lightMode": {
      "logo": "https://yourapp.com/logo.svg",
      "favicon": "https://yourapp.com/favicon.png",
      "pageBackground": "#FAFAFA",
      "buttonBackground": "#1569A8",
      "buttonText": "#FFFFFF",
      "links": "#1569A8"
    },
    "darkMode": {
      "logo": "https://yourapp.com/logo-dark.svg",
      "pageBackground": "#0B0E14",
      "buttonBackground": "#3B82F6",
      "buttonText": "#FFFFFF",
      "links": "#60A5FA"
    }
  }'
```

Read what's currently set:

```bash
curl https://your-app.authaz.io/api/v1/applications/{appId}/branding \
  -H "X-API-Key: $AUTHAZ_API_KEY"
```

## Per-tenant overrides

In multi-tenant apps, each tenant can have its own branding — useful when one tenant signs in at their own subdomain (`auth.acme.com`) and expects the page to feel like Acme, not your platform.

This is opt-in: set **Branding** to **Per Tenant** under *Settings → General → Tenant Customization*. See [Tenancy Customization](./tenancy-customization.md) for the full set of scope toggles. Until you flip the toggle, the Branding page edits the shared application config and there's no tenant picker.

Once enabled, the editor surfaces a tenant picker at the top. Choose a tenant; the editor shows whether an override exists. Save changes to set the override; **Remove tenant branding** restores the application-level default.

```bash
curl -X PUT https://your-app.authaz.io/api/v1/applications/{appId}/tenants/{tenantId}/branding \
  -H "X-API-Key: $AUTHAZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "lightMode": { "buttonBackground": "#FF6F61" } }'

# Remove the override
curl -X DELETE https://your-app.authaz.io/api/v1/applications/{appId}/tenants/{tenantId}/branding \
  -H "X-API-Key: $AUTHAZ_API_KEY"
```

Per-tenant branding is only meaningful when the application's [`brandingScope` is set to `tenant`](./tenancy-customization.md#branding). Single-tenancy apps don't show the picker.

## What about emails?

The transactional email templates pick up your branding automatically — same logo, same primary color, same font where the email client supports it. You can override copy and layout per template under [Communications](./communications.md), but you don't have to re-set the colors there.

## Practical tips

- **Test dark mode.** Most teams forget. Your light palette doesn't auto-translate; pick deliberate dark colors.
- **Logos at 2x.** Display widths are small; use a 2x raster (or SVG) so the logo stays crisp on hi-DPI screens.
- **Background images cost.** A large image slows Universal Login's first paint. If you must use one, host it on a CDN with sensible cache headers, and keep it under ~200 KB.
- **Test the whole journey.** Click through every screen in the preview — login, signup, MFA, password reset, tenant picker, error states. Branding bugs hide in the screens you don't usually see.

## Next steps

- [Custom Domains](./custom-domains.md) — host Universal Login on `auth.yourapp.com` to complete the white-label.
- [Communications](./communications.md) — branded emails matching your login surface.
- [Multi-tenancy](./multi-tenancy.md) — when per-tenant branding makes sense.