PingOne Platform APIs

Branding Themes

Branding themes control the layout, color, and images for the authentication sign-on screens associated with a specified environment. PingOne provides several branding template themes that can be used as-is, or as a starting point for further customization. If a branding theme is not specified, the sign-on screens use Ping Identity default branding.

Branding template configurations

PingOne provides the following branding theme configurations. A branding theme template must be specified in the template property when creating a new branding theme resource:

default

  {
    "name": "default",
    "color": {
      "button": "#2996cc",
      "buttonText": "#ffffff",
      "bodyText": "#686f77",
      "headingText": "#686f77",
      "link": "#2996cc",
      "card": "#ffffff",
      "background": "#ededed"
    },
    "image": {
      "background": ""
    },
    "meta": {
      "displayName": "Ping Default"
    }
  }

focus

{
    "name": "focus",
    "color": {
      "button": "#cb0020",
      "buttonText": "#ffffff",
      "bodyText": "#4a4a4a",
      "headingText": "#cb0020",
      "link": "#2996cc",
      "card": "#fcfcfc",
      "background": "#ededed"
    },
    "image": {
      "background": ""
    },
    "meta": {
      "displayName": "Focus"
    }
  }

mural

{
    "name": "mural",
    "color": {
      "button": "#61b375",
      "buttonText": "#ffffff",
      "bodyText": "#000000",
      "headingText": "#000000",
      "link": "#2996cc",
      "card": "#fcfcfc",
      "background": ""
    },
    "image": {
      "background": "https://assets.pingone.com/ux/branding-themes/0.1.0/mural/bg.jpg"
    },
    "meta": {
      "displayName": "Mural",
      "cssLink": "https://assets.pingone.com/ux/branding-themes/0.1.0/mural/mural.css"
    }
  }

slate

{
    "name": "slate",
    "color": {
      "button": "#fcfcfc",
      "buttonText": "#4a4a4a",
      "bodyText": "#4a4a4a",
      "headingText": "#4a4a4a",
      "link": "#4a4a4a",
      "card": "#fcfcfc",
      "background": ""
    },
    "image": {
      "background": "https://assets.pingone.com/ux/branding-themes/0.1.0/slate/bg.jpg"
    },
    "meta": {
      "displayName": "Slate",
      "cssLink": "https://assets.pingone.com/ux/branding-themes/0.1.0/slate/slate.css"
    }
  }

split

{
    "name": "split",
    "color": {
      "button": "#263956",
      "buttonText": "#ffffff",
      "bodyText": "#263956",
      "headingText": "#686f77",
      "link": "#2996cc",
      "card": "#fcfcfc",
      "background": "#2996cc"
    },
    "image": {
      "background": ""
    },
    "meta": {
      "displayName": "Split"
    }
  }

Branding themes data model

Property Type Required Mutable Description

configuration.backgroundColor

String

Required

Mutable

The background color for the theme. It must be a valid hexadecimal color code, and it is a required property when configuration.backgroundType is set to COLOR.

configuration.backgroundImage.href

String

Required

Mutable

The URL or fully qualified path to the background image file used for branding. This is a required property when configuration.backgroundType is set to IMAGE.

configuration.backgroundImage.id

String

Required

Immutable

The ID of the background image.

configuration.backgroundOutlineColor

String

Optional

Mutable

For PingOne Neo verification presentation screen, the outline color of background objects for the branding theme. It must be a valid hexadecimal color code. Defaults to #A5B9C5.

configuration.backgroundType

String

Required

Mutable

The background type for the theme. Options are NONE, COLOR, IMAGE, DEFAULT.

configuration.bodyTextColor

String

Required

Mutable

The body text color for the theme. It must be a valid hexadecimal color code.

configuration.buttonBorderColor

String

Optional

Mutable

The button border color for the theme. It must be a valid hexadecimal color code.

configuration.buttonBorderWidth

String

Optional

Mutable

The button border width for the theme (range from 0-4px).

configuration.buttonCornerRadius

String

Optional

Mutable

The button border radius for the theme (range between 0-25px).

configuration.buttonColor

String

Required

Mutable

The button color for the theme. It must be a valid hexadecimal color code.

configuration.buttonHoverStateBorderColor

String

Optional

Mutable

The button hover state border color for the theme. It must be a valid hexadecimal color code.

configuration.buttonHoverStateFillColor

String

Optional

Mutable

The button hover state fill color for the theme. It must be a valid hexadecimal color code.

configuration.buttonHoverStateTextColor

String

Optional

Mutable

The button hover state text color for the theme. It must be a valid hexadecimal color code.

configuration.buttonTextColor

String

Required

Mutable

The button text color for the branding theme. It must be a valid hexadecimal color code.

configuration.buttonTextSize

String

Optional

Mutable

The button text size for the theme.

configuration.buttonTextWeight

String

Optional

Mutable

The button text weight for the theme (range from 100-900).

configuration.cardBorderColor

String

Optional

Mutable

The card border color for the theme. It must be a valid hexadecimal color code.

configuration.cardBorderWidth

String

Optional

Mutable

The card border width for the theme (range from 0-4px).

configuration.cardColor

String

Required

Mutable

The card color for the branding theme. It must be a valid hexadecimal color code.

configuration.cardCornerRadius

String

Optional

Mutable

The card corner radius for the theme (range from 0-25px).

configuration.cardHorizontalAlignment

String

Optional

Mutable

The card horizontal alignment for the theme.

configuration.cardShadow

String

Optional

Mutable

The card shadow for the theme.

configuration.cardVerticalAlignment

String

Optional

Mutable

The card vertical alignment for the theme.

configuration.focusRectangleColor

String

Optional

Mutable

The focus rectangle color for the theme. It must be a valid hexadecimal color code.

configuration.footer

String

Optional

Mutable

The footer of the branding theme.

configuration.foregroundHighlightColor

String

Optional

Mutable

For PingOne Neo verification presentation screen, the highlight color of the foreground object for the branding theme. It must be a valid hexadecimal color code. Defaults to #C6D9FF.

configuration.foregroundMainColor

String

Optional

Mutable

For PingOne Neo verification presentation screen, the outline color of the foreground object for the branding theme. It must be a valid hexadecimal color code. Defaults to #4462ED.

configuration.globalFont

String

Optional

Mutable

The global font for the theme. The default value is Helvetica Neue, Helvetica, sans-serif.

configuration.header

String

Optional

Mutable

The header for the theme. For example, "<h1>Welcome to PingOne<h1>".

configuration.headingTextColor

String

Required

Mutable

The heading text color for the branding theme. It must be a valid hexadecimal color code.

configuration.inputBorderWidth

String

Optional

Mutable

The input border width for the theme (range from 0-4px).

configuration.inputBoxBorderColor

String

Optional

Mutable

The input box border color for the theme. It must be a valid hexadecimal color code.

configuration.inputCornerRadius

String

Optional

Mutable

The input corner radius for the theme (range from 0-25px).

configuration.inputLabelPosition

String

Optional

Mutable

The input label position for the theme.

configuration.inputLabelTextColor

String

Optional

Mutable

The input label text color for the theme. It must be a valid hexadecimal color code.

configuration.inputLabelTextSize

String

Optional

Mutable

The input label text size for the theme.

configuration.inputLabelTextWeight

String

Optional

Mutable

The input label text weight for the theme (range from 100-900).

configuration.inputValueTextColor

String

Optional

Mutable

The input value text color for the theme. It must be a valid hexadecimal color code.

configuration.inputValueTextSize

String

Optional

Mutable

The input value text size for the theme.

configuration.inputValueTextWeight

String

Optional

Mutable

The input value text weight for the theme (range from 100-900).

configuration.linkTextColor

String

Required

Mutable

The hyperlink text color for the branding theme. It must be a valid hexadecimal color code.

configuration.linkTextHoverColor

String

Optional

Mutable

The link text hover color for the theme. It must be a valid hexadecimal color code.

configuration.linkTextSize

String

Optional

Mutable

The link text size for the theme.

configuration.linkTextWeight

String

Optional

Mutable

The link text weight for the theme (range from 100-900).

configuration.logo.href

String

Required

Mutable

The URL or fully qualified path to the logo file used for branding. This is a required property when configuration.logoType is set to IMAGE.

configuration.logo.id

String

Required

Immutable

The ID of the logo image.

configuration.logoHeight

String

Optional

Mutable

The logo height assigned to the image (range from 0-100px).

configuration.logoType

String

Required

Mutable

The type of format used for the image. Options are IMAGE and NONE.

configuration.name

String

Required

Mutable

The name of the branding theme.

configuration.schemaVersion

Integer

Read only

N/A

The schema version number for the theme.

configuration.subTitleTextColor

String

Optional

Mutable

The subtitle text color for the theme. It must be a valid hexadecimal color code.

configuration.subTitleTextSize

String

Optional

Mutable

The subtitle text size for the theme.

configuration.subTitleTextWeight

String

Optional

Mutable

The subtitle text weight for the theme (range from 100-900).

configuration.titleTextSize

String

Optional

Mutable

The title text size for the theme.

configuration.TitleTextWeight

String

Optional

Mutable

The title text width for the theme (range from 100-900).

configuration.applicationBackgroundColor

String

Optional

Mutable

The application background color for the theme. It must be a valid hexadecimal color code. Note that this property is not used by DaVinci forms.

configuration.headerBackgroundColor

String

Optional

Mutable

The header background color for the theme. It must be a valid hexadecimal color code. Note that this property is not used by DaVinci forms.

configuration.headerLocalized

Object

Optional

Mutable

The localization object to specify language translations for the form header.

configuration.headerLocalized.defaultLanguage

String

Optional

Mutable

The localization language code for the header’s default language (for example, "defaultLanguage": "en").

configuration.headerLocalized.content

Object

Optional

Mutable

The localization language object that specifies the localized text and content type for the language options.

configuration.headerLocalized.content.{{languageCode}}

Object

Optional

Mutable

The localization language object that specifies the localized text and content type for the specific language.

configuration.headerLocalized.content.{{languageCode}}.inputText

String

Optional

Mutable

The header text in the specified language.

configuration.headerLocalized.content.{{languageCode}}.contentType

String

Optional

Mutable

The content type for the header text in the specified language. Options are RichText and HTML.

configuration.footerLocalized

Object

Optional

Mutable

The localization object to specify language translations for the form footer.

configuration.footerLocalized.defaultLanguage

String

Optional

Mutable

The localization language code for the footer’s default language (for example, "defaultLanguage": "en").

configuration.footerLocalized.content

Object

Optional

Mutable

The localization language object that specifies the localized text and content type for the language options.

configuration.footerLocalized.content.{{languageCode}}

Object

Optional

Mutable

The localization language object that specifies the localized text and content type for the specific language.

configuration.footerLocalized.content.{{languageCode}}.inputText

String

Optional

Mutable

The footer text in the specified language.

configuration.footerLocalized.content.{{languageCode}}.contentType

String

Optional

Mutable

The content type for the footer text in the specified language. Options are RichText and HTML.

default

Boolean

Required

Mutable

Indicates whether this theme is the environment’s default branding configuration. This is used when no theme is specifically associated with an authentication flow. Only one theme can be the default at any time.

environment.id

String

Required

Immutable

The environment resource’s unique identifier associated with the branding theme.

id

String

Required

Immutable

The ID of the branding configuration resource.

template

String

Required

Mutable

The template name of the branding theme associated with the environment. Options are default, focus, mural, slate, and split.

Locations of configuration attributes backgroundOutlineColor, foregroundMainColor, and foregroundHighlightColor in the PingOne Neo Verify application.

PingOne Neo verification theme color locations

Response codes

Code Message

200

Successful operation.

201

Successfully created.

400

The request could not be completed.

401

You do not have access to this resource.

403

You do not have permissions or are not licensed to make this request.

404

The requested resource was not found.

500

Unexpected server error.

Branding theme errors

In addition to the general error codes, branding theme operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [<property> <message>] for request-body property omissions, or The request could not be completed. One or more validation errors were in the request. for the template-specific property check.

When and details

When: A POST /themes or PUT /themes/{themeID} request omits the required template or configuration property (POST) or the required configuration property (PUT), omits a required configuration property (logoType, backgroundType, name, and the required text colors), omits the logo when logoType is IMAGE, omits the backgroundImage when backgroundType is IMAGE, omits the backgroundColor when backgroundType is COLOR, or omits the headerBackgroundColor when the selected template requires one

Details: Describes the failing property, such as must not be null for an omitted template, configuration, logoType, or backgroundType, must not be blank for an omitted or blank configuration property (such as name or the required text colors), or This field is required. for a conditionally required property, for example Validation Error : [configuration.bodyTextColor must not be blank].

400

INVALID_DATA

INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST /themes or PUT /themes/{themeID} request supplies a color value that is not a hex color code, or an image URL that is not valid (logo, backgroundImage, or favIcon hrefs)

Details: is not a valid hex color code for an invalid color, or must be a valid URL with http/https scheme for an image URL, for example Validation Error : [configuration.bodyTextColor is not a valid hex color code].

400

INVALID_REQUEST

None

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A path identifier cannot be parsed as a UUID

Details: None. The top‑level code is INVALID_REQUEST even though the message text is the INVALID_DATA default message.

400

INVALID_REQUEST

INVALID_VALUE or None

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A POST /themes or PUT /themes/{themeID} request body cannot be deserialized, for example an unrecognized logoType or backgroundType value

Details: For a JSON field conversion error, the target is the field path. Otherwise no detail is returned.

400

REQUEST_FAILED

None

Message: The template name does not exist.

When and details

When: A POST /themes request supplies a template name that does not exist

Details: None.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST /themes or a clone request would exceed the maximum number of themes for the environment

Details: Environments cannot have more than <maximum> themes.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A PUT /themes/{themeID}/default request sets defaultTheme to false

Details: Environments must have a default theme.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A DELETE /themes/{themeID} request deletes the environment’s default theme

Details: Cannot delete default theme.

400

REQUEST_FAILED

CONSTRAINT_VIOLATION

Message: The request could not be completed. There was an issue processing the request.

When and details

When: A POST /themes/{themeID}/migrate request migrates a theme that is already version 2, or when the branding customization feature flag is off for the environment

Details: Theme is already version 2. or Branding customization feature flag must be enabled to migrate theme.

403

ACCESS_FAILED

LICENSE_EXCEEDED

Message: This service is no longer active.

When and details

When: The environment is disabled for platform usage (applies to all branding theme operations)

Details: Environment is disabled: <environmentId>. The servlet filter that performs this check reuses the controller advice mapping, so the status and body format match controller errors.

403

ACCESS_FAILED

None

Message: The actor attempting to perform the request is not authorized.

When and details

When: The actor lacks the branding:read:theme permission (GET operations), the branding:create:theme permission (POST, including clone), the branding:update:theme permission (PUT, including default and migrate), or the branding:delete:theme permission (DELETE). The permission values in the request are not logged.

Details: None.

404

NOT_FOUND

None

Message: The request could not be completed. The requested resource was not found.

When and details

When: GET /themes/{themeID}, PUT /themes/{themeID}, DELETE /themes/{themeID}, or the clone or migrate operations reference a theme that does not exist in the environment

Details: None.

400

UNEXPECTED_ERROR

None

Message: There was an unexpected error with the service. Please try again later.

When and details

When: The theme cannot be published to storage after the change is saved, or the theme’s template is missing from the template definitions during an update or migration. The saved change is reverted before the storage error is returned. The service’s controller advice maps any ApiException without a LICENSE_EXCEEDED detail to a 400 response

Details: None.