---
title: "Create or update login branding"
method: PUT
path: "/clusters/{cluster_id}/realms/{realm}/branding/login"
tags: ["Login Branding"]
---

# Create or update login branding

`PUT /clusters/{cluster_id}/realms/{realm}/branding/login`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/clusters/{cluster_id}/realms/{realm}/branding/login`
- Auth: API key in header `API-Key`

Creates or replaces the login page branding for a realm. Triggers asynchronous theme generation and deployment; poll the `status` field to confirm completion.

Required scope: `branding:write`

## Path parameters

- `cluster_id` string, uuid, required
- `realm` string, required: Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.

## Headers

- `API-Version` '2026-06-01.beta', required

## Request body

- UpsertLoginBrandingRequest
  - `primary_color` string: CSS hex color code.
  - `background_color` string: CSS hex color code.
  - `logo_url` string, uri
  - `favicon_url` string, uri
  - `font_url` string, uri
  - `font_family` string: CSS font-family name used with `font_url`: letters, digits, spaces, hyphens and underscores only. Omitted means unchanged.
  - `apply_to_account_console` boolean: Apply the login branding to the realm's account console. Omitted means unchanged.
  - `apply_to_admin_console` boolean: Apply the login branding to the realm's admin console. Omitted means unchanged.
  - `registration_enabled` boolean: Sets the realm's own self-registration setting (Keycloak registrationAllowed). Omitted means unchanged: unlike the other fields, leaving it out does not reset it to a default.
  - `remember_me_enabled` boolean
  - `forgot_password_enabled` boolean
  - `terms_of_service_url` string, uri
  - `privacy_policy_url` string, uri
  - `show_powered_by` boolean
  - `sso` SsoConfig
    - `enabled` boolean, required: Show identity provider buttons on the login page.
    - `layout` 'vertical' | 'horizontal', required
    - `display_style` 'logo_only' | 'logo_with_text' | 'text_only', required
    - `button_size` 'small' | 'medium' | 'large', required
  - `internationalization` LoginInternationalizationConfig: Login page internationalization settings.
    - `enabled` boolean, required
    - `default_locale` string, required: IETF BCP 47 language tag used as the default locale.
    - `supported_locales` string[], required: Locales available to users. Must include `default_locale`.
    - `language_selector_style` 'dropdown' | 'text_labels' | 'flags', required
    - `language_selector_position` 'top_right' | 'top_left' | 'top_middle' | 'form_inside_header' | 'form_inside_left', required
    - `language_selection_mode` 'automatic_with_selector' | 'automatic_only' | 'selector_only' | 'hide_selector', required

## Response `200`

The request has succeeded.

- LoginBranding: Login page branding configuration for a Keycloak realm.
  - `cluster_id` string, uuid, required
  - `realm` string, required: Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.
  - `primary_color` string: CSS hex color code.
  - `background_color` string: CSS hex color code.
  - `logo_url` string, uri: URL of the logo displayed on the login page.
  - `favicon_url` string, uri
  - `font_url` string, uri: URL of a custom web font.
  - `font_family` string: CSS font-family name used with `font_url`, for example `Inter`.
  - `apply_to_account_console` boolean: Whether the realm's account console uses the login branding.
  - `apply_to_admin_console` boolean: Whether the realm's admin console uses the login branding.
  - `theme_name` string: The realm's current Keycloak login theme, read live from the realm. Every branding save installs the theme under a new name, so read it from here rather than pinning it in realm configuration. Absent when the realm uses Keycloak's default theme.
  - `registration_enabled` boolean, required: The realm's own self-registration setting (Keycloak registrationAllowed), read live from the realm. It is the same field the realm API exposes as registration_allowed; branding keeps no copy of it.
  - `remember_me_enabled` boolean, required
  - `forgot_password_enabled` boolean, required
  - `terms_of_service_url` string, uri
  - `privacy_policy_url` string, uri
  - `show_powered_by` boolean, required: Display a 'Powered by Skycloak' badge in the footer.
  - `sso` SsoConfig
    - `enabled` boolean, required: Show identity provider buttons on the login page.
    - `layout` 'vertical' | 'horizontal', required
    - `display_style` 'logo_only' | 'logo_with_text' | 'text_only', required
    - `button_size` 'small' | 'medium' | 'large', required
  - `internationalization` LoginInternationalizationConfig: Login page internationalization settings.
    - `enabled` boolean, required
    - `default_locale` string, required: IETF BCP 47 language tag used as the default locale.
    - `supported_locales` string[], required: Locales available to users. Must include `default_locale`.
    - `language_selector_style` 'dropdown' | 'text_labels' | 'flags', required
    - `language_selector_position` 'top_right' | 'top_left' | 'top_middle' | 'form_inside_header' | 'form_inside_left', required
    - `language_selection_mode` 'automatic_with_selector' | 'automatic_only' | 'selector_only' | 'hide_selector', required
  - `status` 'applying' | 'applied' | 'failed', required
  - `applied_at` string, date-time: Timestamp of the most recent successful deployment to Keycloak.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `422`: Client error
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)