Create or update email branding

PUT

/clusters/{cluster_id}/realms/{realm}/branding/email

const url = 'http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/realms/customer-portal/branding/email';
const options = {
  method: 'PUT',
  headers: {
    'API-Version': '2026-06-01.beta',
    'API-Key': '<API-Key>',
    'Content-Type': 'application/json'
  },
  body: '{"primary_color":"#1a73e8","header_logo_light_url":"https://example.com","header_logo_dark_url":"https://example.com","company_url":"https://example.com","footer_company_name":"example","footer_text":"example","show_powered_by":true,"internationalization":{"enabled":true,"default_locale":"example","supported_locales":["example"]}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url http://localhost:8000/clusters/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/realms/customer-portal/branding/email \
  --header 'API-Key: <API-Key>' \
  --header 'API-Version: 2026-06-01.beta' \
  --header 'Content-Type: application/json' \
  --data '{ "primary_color": "#1a73e8", "header_logo_light_url": "https://example.com", "header_logo_dark_url": "https://example.com", "company_url": "https://example.com", "footer_company_name": "example", "footer_text": "example", "show_powered_by": true, "internationalization": { "enabled": true, "default_locale": "example", "supported_locales": [ "example" ] } }'

Creates or replaces the email template branding for a realm. Triggers asynchronous theme generation and deployment.

Required scope: branding:write

Authorizations

ApiKeyAuth

Parameters

Path Parameters

cluster_id

required

string format: uuid

realm

required

Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.

string

>= 1 characters <= 63 characters /^[a-zA-Z][a-zA-Z0-9-]*$/

Example

customer-portal

Header Parameters

API-Version

required

string

Allowed values: 2026-06-01.beta

Request Body^required

application/json

object

primary_color

CSS hex color code.

string

Example

#1a73e8

header_logo_light_url

string format: uri

header_logo_dark_url

string format: uri

company_url

string format: uri

footer_company_name

string

<= 100 characters

footer_text

string

<= 500 characters

show_powered_by

Display a ‘Powered by Skycloak’ line in the email footer. Hiding it requires a plan that allows removing branding; otherwise it stays on. Omitted means unchanged.

boolean

internationalization

Internationalization settings.

object

enabled

required

boolean

default_locale

required

IETF BCP 47 language tag used as the default locale.

string

>= 2 characters <= 20 characters

supported_locales

required

Locales available to users. Must include default_locale.

Array<string>

>= 1 items

Responses

200

The request has succeeded.

application/json

Email template branding configuration for a Keycloak realm.

object

cluster_id

required

string format: uuid

realm

required

Keycloak realm name (not ID). Must start with a letter; allows letters, digits, and hyphens.

string

>= 1 characters <= 63 characters /^[a-zA-Z][a-zA-Z0-9-]*$/

primary_color

Primary accent color used in email templates.

string

header_logo_light_url

Logo URL for light-background email clients.

string format: uri

header_logo_dark_url

Logo URL for dark-background email clients.

string format: uri

company_url

URL of the company website linked from the email footer.

string format: uri

footer_company_name

string

<= 100 characters

footer_text

string

<= 500 characters

show_powered_by

Display a ‘Powered by Skycloak’ line in the email footer.

boolean

internationalization

Internationalization settings.

object

enabled

required

boolean

default_locale

required

IETF BCP 47 language tag used as the default locale.

string

>= 2 characters <= 20 characters

supported_locales

required

Locales available to users. Must include default_locale.

Array<string>

>= 1 items

status

required

string

Allowed values: applying applied failed

applied_at

Timestamp of the most recent successful deployment to Keycloak.

string format: date-time

created_at

required

string format: date-time

updated_at

required

string format: date-time

Example

{
  "realm": "customer-portal",
  "primary_color": "#1a73e8",
  "status": "applying"
}

400

The server could not understand the request due to invalid syntax.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

401

Access is unauthorized.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

403

Access is forbidden.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

404

The server cannot find the requested resource.

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

422

Client error

application/problem+json

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

errors

required

Array<object>

>= 1 items

object

field

required

string

detail

required

string

code

string

value

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com",
  "errors": [
    {
      "field": "example",
      "detail": "example",
      "code": "example",
      "value": "example"
    }
  ]
}

429

Client error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Headers

Retry-After

integer

RateLimit-Limit

integer

RateLimit-Remaining

integer

RateLimit-Reset

integer

X-RateLimit-Limit-Second

integer

X-RateLimit-Remaining-Second

integer

X-RateLimit-Limit-Minute

integer

X-RateLimit-Remaining-Minute

integer

X-RateLimit-Limit-Hour

integer

X-RateLimit-Remaining-Hour

integer

X-RateLimit-Limit-Day

integer

X-RateLimit-Remaining-Day

integer

500

Server error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

501

Server error

application/problem+json

RFC 9457 Problem Details object.

object

type

required

string format: uri

title

required

string

status

required

integer

detail

required

string

instance

string format: uri

Example ^generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "https://example.com"
}

Create or update email branding

Authorizations

Parameters

Path Parameters

Example

Header Parameters

Request Bodyrequired

Example

Responses

200

Example

400

Example generated

401

Example generated

403

Example generated

404

Example generated

422

Example generated

429

Example generated

Headers

500

Example generated

501

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated