Themes

These endpoints allow you to customize the look and feel of pages and templates, including the following:

  • The Okta-hosted sign-in page
  • The sign-out page
  • Error pages
  • Email templates
  • The Okta End-User Dashboard

Each new org contains Okta default branding. You can upload your own assets (colors, background image, logo, and favicon) to replace the default assets. Then you can publish these assets directly to your pages and templates.

Notes:

  • Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.
  • Okta optimizes the primaryColorContrastHex and secondaryColorContrastHex properties for the highest contrast between the font color and the background or button color. To disable or override the contrast auto-detection, update either contrast value with an accepted contrast hex code. Any update disables future automatic optimizations for the contrast hex.
  • Contrast color is used by pages to optimize the opacity of text color when primary or secondary color is used as the background.

List all themes
OAuth 2.0: okta.brands.read

Lists all the themes in your brand.

Important: Currently each org supports only one Theme, therefore this contains a single object only.

Request
path Parameters
brandId
required
string

The ID of the brand

Responses
200

Successfully returned the list of themes

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/brands/{brandId}/themes
Request samples 
Response samples 
application/json
[]
Retrieve a theme
OAuth 2.0: okta.brands.read
Retrieves a theme for a brand


Request 
path Parameters
brandId
required
string
The ID of the brand


 
themeId
required
string
The ID of the theme


 
Responses 
200
Successfully retrieved the theme


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/themes/{themeId}
Request samples 
Response samples 
application/json
{}
Replace a theme
OAuth 2.0: okta.brands.manage
Replaces a theme for a brand


Request 
path Parameters
brandId
required
string
The ID of the brand


 
themeId
required
string
The ID of the theme


 
Request Body schema: application/json
required
primaryColorHex
required
string
 Default:  null
Primary color hex code


 
secondaryColorHex
required
string
 Default:  null
Secondary color hex code


 
signInPageTouchPointVariant
required
string (SignInPageTouchPointVariant) 
Variant for the Okta sign-in page. You can publish a theme for sign-in page with different combinations of assets. Variants are preset combinations of those assets.




Note:  For a non-OKTA_DEFAULT variant, primaryColorHex is used for button background color and primaryColorContrastHex is used to optimize the opacity for button text.




 Enum: Description
BACKGROUND_IMAGE
Uses the logo, favicon, and background image from the Theme


BACKGROUND_SECONDARY_COLOR
Uses the logo and favicon from the Theme. Uses secondaryColorHex as the background color for the Okta sign-in page.


OKTA_DEFAULT
Uses the Okta logo and favicon with no background image. Uses the Okta colors on the Okta sign-in page.


 
endUserDashboardTouchPointVariant
required
string (EndUserDashboardTouchPointVariant) 
 Default:  "OKTA_DEFAULT"
Variant for the Okta End-User Dashboard. You can publish a theme for end-user dashboard with different combinations of assets. Variants are preset combinations of those assets.


 Enum: Description
FULL_THEME
Uses the logo and favicon from the Theme. Uses primaryColorHex for the logo and the side navigation bar background color.


LOGO_ON_FULL_WHITE_BACKGROUND
Uses the logo and favicon from the Theme. Uses white background color for the logo and the side navigation bar background color.


OKTA_DEFAULT
Uses the Okta logo and favicon. Uses a white background color for the logo and the side navigation bar background color.


WHITE_LOGO_BACKGROUND
Uses the logo and favicon from the Theme, with a white background color for the logo. Uses primaryColorHex for the side navigation bar background color.


 
errorPageTouchPointVariant
required
string (ErrorPageTouchPointVariant) 
 Default:  "OKTA_DEFAULT"
Variant for the error page. You can publish a theme for error page with different combinations of assets. Variants are preset combinations of those assets.


 Enum: Description
BACKGROUND_IMAGE
Uses the logo, favicon, and background image from the Theme


BACKGROUND_SECONDARY_COLOR
Uses the logo and favicon from the Theme. Uses secondaryColorHex as the background color for the error page.


OKTA_DEFAULT
Uses the Okta logo, favicon, and background color


 
emailTemplateTouchPointVariant
required
string (EmailTemplateTouchPointVariant) 
 Default:  "OKTA_DEFAULT"
Variant for email templates. You can publish a theme for email templates with different combinations of assets. Variants are preset combinations of those assets.


 Enum: Description
FULL_THEME
Uses the Okta logo and Okta colors in email templates


OKTA_DEFAULT
Uses the logo from the Theme. Uses primaryColorHex as the background color for buttons.


 
loadingPageTouchPointVariant
string (LoadingPageTouchPointVariant) 
 Default:  "OKTA_DEFAULT"
Variant for the Okta loading page. You can publish a theme for Okta loading page with different combinations of assets. Variants are preset combinations of those assets.


 Enum: Description
NONE
Uses no loading page animation during the redirect


OKTA_DEFAULT
Uses the default Okta loading page animation during the redirect


 
primaryColorContrastHex
string
 Default:  null
Primary color contrast hex code


 
secondaryColorContrastHex
string
 Default:  null
Secondary color contrast hex code


 
Responses 
200
Successfully replaced the theme


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/brands/{brandId}/themes/{themeId}
Request samples 
application/json
{
  • "primaryColorHex": "#1662dd",
  • "primaryColorContrastHex": "#000000",
  • "secondaryColorHex": "#ebebed",
  • "secondaryColorContrastHex": "#000000",
  • "signInPageTouchPointVariant": "OKTA_DEFAULT",
  • "endUserDashboardTouchPointVariant": "OKTA_DEFAULT",
  • "errorPageTouchPointVariant": "OKTA_DEFAULT",
  • "emailTemplateTouchPointVariant": "OKTA_DEFAULT",
  • "loadingPageTouchPointVariant": "OKTA_DEFAULT"
}
Response samples 
application/json
{}
Upload the background image
OAuth 2.0: okta.brands.manage
Uploads and replaces the background image for the theme. The file must be in PNG, JPG, or GIF format and less than 2 MB in size.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
themeId
required
string
The ID of the theme


 
Request Body schema: multipart/form-data
background image file


file
required
string <binary> 
 
Responses 
201
Content Created


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/brands/{brandId}/themes/{themeId}/background-image
Request samples 
Response samples 
application/json
{
  • "url": "string"
}
Delete the background image
OAuth 2.0: okta.brands.manage
Deletes a Theme background image


Request 
path Parameters
brandId
required
string
The ID of the brand


 
themeId
required
string
The ID of the theme


 
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/brands/{brandId}/themes/{themeId}/background-image
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Upload the favicon
OAuth 2.0: okta.brands.manage
Uploads and replaces the favicon for the theme


Request 
path Parameters
brandId
required
string
The ID of the brand


 
themeId
required
string
The ID of the theme


 
Request Body schema: multipart/form-data
favicon file


file
required
string <binary> 
 
Responses 
201
Created


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/brands/{brandId}/themes/{themeId}/favicon
Request samples 
Response samples 
application/json
{
  • "url": "string"
}
Delete the favicon
OAuth 2.0: okta.brands.manage
Deletes a Theme favicon. The theme will use the default Okta favicon.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
themeId
required
string
The ID of the theme


 
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/brands/{brandId}/themes/{themeId}/favicon
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}