Development Guides Home

Guide to cPanel Interface Customization and Branding - Branding Customization

Note:

This guide only applies to the Jupiter theme. For customization options in the Paper Lantern theme, read our Guide to cPanel Interface Customization and Branding in the Paper Lantern Theme


Introduction

You can use API functions to customize the cPanel interface in the Jupiter theme. Currently, you can change the appearance by using custom colors and custom logos.

Branding modifies the cPanel interface to match your company's logo and brand. Branding options include custom colors and logos.

Custom colors

You can modify the appearance of the cPanel interface to match your company's logo and brand. You can change the primary color and the accent color using hex codes. All colors in the interface use varying opacities of the selected primary color calculated by the API. Text colors on the main menu and icon colors on the header badges display as black or white depending on the color contrast ratio.

cPanel Interface Jupiter Tools Page Colors cPanel Interface Jupiter Solutions Page Colors

You can add your company logo to the cPanel interface. You can add a logo for a light background and a logo for a dark background. The cPanel interface will automatically select the logo with the most contrast. If you only upload one logo, the cPanel interface will display this logo for both light and dark backgrounds. For example, if the only logo uploaded is a white logo, it will display on a light background as well as a dark. This could make your logo difficult to see. For best results, upload both a light and dark logo.

Important:

The WHM API update_customizations function only accepts SVG images for logos. You must Base64 encode your SVG image. To add your logo in the API call, URL encode the Base64 encoded image.


WHM API functions

Server owners and resellers can use WHM API functions to update, retrieve, and delete customizations.

We strongly discourage system administrators from manually editing JSON files. Use the appropriate API function to make changes to the cPanel interface.

Using WHM API functions as a server owner or root-enabled reseller

Server owners can use the API Shell to call a WHM API 1 function. To customize the cPanel interface, use the following API functions:

WHM API Function Description
update_customizations This function updates the primary and accent colors in the cPanel interface and adds custom logos to the cPanel interface.
retrieve_customizations This function displays customizations made to the cPanel interface.
delete_customizations This function deletes customizations made to the cPanel interface.

Using WHM API functions as a reseller without root privileges

Only root enabled or root-enabled resellers can use the API Shell. If you are a reseller without root access, you must create an API token. Once you have an API token, use the command line to log into WHM as a reseller with your API token to update, delete, or retrieve your customizations.

The following examples use username for your reseller name and IDYXLNQL3TXSAGPR0SLOYKIGAKYNRR16 for the saved API token.

update_customizations

This function only accepts SVG values for logos. You must Base64 encode your SVG image.

To customize colors or add a logo, run the following command with your hex color codes and Base64 encoded string. The following curl command with --data-urlencode will URL encode the Base64 encoded string.

curl -k -H"Authorization: whm username:IDYXLNQL3TXSAGPR0SLOYKIGAKYNRR16" \
  'https://hostname.example.com:2087/json-api/update_customizations?api.version=1' \
  --data-urlencode 'application=cpanel' \
  --data-urlencode 'theme=jupiter' \
  --data-urlencode 'brand={
      "brand" :
          {"colors" : {
              "accent" : "#cc33ff",
              "primary" : "#006122"
          },
          "logo" : {
              "description" : "The logo for SuperReseller, LLC",

              "forDarkBackground" : "PHN2ZyB3aWR0aD0iMTc1IiBoZWlnaHQ9IjUwIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAw MC9zdmciPjxyZWN0IHg9IjIiIHk9IjIiIHdpZHRoPSIxNzEiIGhlaWdodD0iNDYiIHN0eWxlPSJm aWxsOiMwMGZmNDg7c3Ryb2tlOiNmZmZmZmY7c3Ryb2tlLXdpZHRoOjIiLz48dGV4dCB4PSI1MCUi IHk9IjUwJSIgZm9udC1zaXplPSIxOCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgYWxpZ25tZW50LWJh c2VsaW5lPSJtaWRkbGUiIGZvbnQtZmFtaWx5PSJtb25vc3BhY2UsIHNhbnMtc2VyaWYiIGZpbGw9 IiNmZmZmZmYiPnJlc2VsbGVyPC90ZXh0Pjwvc3ZnPg==",

              "forLightBackground" : "PHN2ZyB3aWR0aD0iMTc1IiBoZWlnaHQ9IjUwIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAw%20MC9zdmciPjxyZWN0IHg9IjIiIHk9IjIiIHdpZHRoPSIxNzEiIGhlaWdodD0iNDYiIHN0eWxlPSJm%20aWxsOiMwMDA0ZmY7c3Ryb2tlOiNmZmZmZmY7c3Ryb2tlLXdpZHRoOjIiLz48dGV4dCB4PSI1MCUi%20IHk9IjUwJSIgZm9udC1zaXplPSIxOCIgdGV4dC1hbmNob3I9Im1pZGRsZSIgYWxpZ25tZW50LWJh%20c2VsaW5lPSJtaWRkbGUiIGZvbnQtZmFtaWx5PSJtb25vc3BhY2UsIHNhbnMtc2VyaWYiIGZpbGw9%20IiNmZmZmZmYiPnJlc2VsbGVyLWx0PC90ZXh0Pjwvc3ZnPg%3D%3D"}}}'

retrieve_customizations

To display customizations made to the cPanel interface, run the following command:

curl -s -k -H"Authorization: whm username:IDYXLNQL3TXSAGPR0SLOYKIGAKYNRR16" \
'https://hostname.example.com:2087/json-api/retrieve_customizations?api.version=1' \
        --data-urlencode 'application=cpanel' \
        --data-urlencode 'theme=jupiter'

delete_customizations

To delete customizations made to the cPanel interface, run the following command:

curl -s -k -H"Authorization: whm username:IDYXLNQL3TXSAGPR0SLOYKIGAKYNRR16" \
'https://hostname.example.com/json-api/delete_customizations?api.version=1' \
        --data-urlencode 'application=cpanel' \
        --data-urlencode 'theme=jupiter'

For more information, read our API Tokens in WHM and Manage API Tokens in WHM.