Customizations

The Brands API allows you to customize the look and feel of pages and templates, such as the Okta-hosted sign-in page, error pages, email templates, and 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 and publish these assets directly to your pages and templates.

List all Brands
OAuth 2.0: okta.brands.read

Lists all the brands in your org

Request
query Parameters
expand
Array of strings

Specifies additional metadata to be included in the response

Items Enum: "themes" "domains" "emailDomain"
after
string

The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.

limit
integer [ 1 .. 200 ]
Default: 20

A limit on the number of objects to return

q
string

Searches the records for matching value

Responses
200

OK

403

Forbidden

429

Too Many Requests

get/api/v1/brands
Request samples 
Response samples 
application/json
[]
Create a Brand
OAuth 2.0: okta.brands.manage
Creates a new brand in your org


Request 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Enum: "themes" "domains" "emailDomain"  
after
string
The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.


 
limit
integer  [ 1 .. 200 ] 
 Default:  20
A limit on the number of objects to return


 
q
string
Searches the records for matching value


 
Request Body schema: application/json
name
required
string
 
Responses 
201
Created


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/brands
Request samples 
application/json
{
  • "name": "My Awesome Brand"
}
Response samples 
application/json
{}
Retrieve a Brand
OAuth 2.0: okta.brands.read
Retrieves a brand by brandId


Request 
path Parameters
brandId
required
string
The ID of the brand


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Enum: "themes" "domains" "emailDomain"  
Responses 
200
OK


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}
Request samples 
Response samples 
application/json
{}
Replace a Brand
OAuth 2.0: okta.brands.manage
Replaces a brand by brandId


Request 
path Parameters
brandId
required
string
The ID of the brand


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Enum: "themes" "domains" "emailDomain"  
Request Body schema: application/json
required
agreeToCustomPrivacyPolicy
boolean
 
customPrivacyPolicyUrl
string
 
object (DefaultApp) 
 
appInstanceId
string
 
appLinkName
string
 
classicApplicationUri
string
 
emailDomainId
string
 
locale
string (Language) 
The language specified as an IETF BCP 47 language tag


 
name
string
 
removePoweredByOkta
boolean
 
Responses 
200
OK


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/brands/{brandId}
Request samples 
application/json
{
  • "customPrivacyPolicyUrl": "https://www.someHost.com/privacy-policy",
  • "agreeToCustomPrivacyPolicy": true,
  • "removePoweredByOkta": true,
  • "name": "New Name For Brand",
  • "emailDomainId": "OeD114iNkrcN6aR680g4",
  • "locale": "en",
  • "defaultApp": {
    • "appInstanceId": "0oa114iNkrcN6aR680g4",
    • "appLinkName": null,
    • "classicApplicationUri": null
    }
}
Response samples 
application/json
{}
Delete a brand
OAuth 2.0: okta.brands.manage
Deletes a brand by brandId


Request 
path Parameters
brandId
required
string
The ID of the brand


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Enum: "themes" "domains" "emailDomain"  
Responses 
204
Successfully deleted the brand.


403
Forbidden


404
Not Found


409
Conflict


429
Too Many Requests


delete/api/v1/brands/{brandId}
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": [ ]
}
List all Domains associated with a Brand
OAuth 2.0: okta.brands.read
Lists all domains associated with a brand by brandId


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
OK


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/domains
Request samples 
Response samples 
application/json
[
  • {
    • "brandId": "bndul904tTZ6kWVhP0g3",
    • "certificateSourceType": "MANUAL",
    • "dnsRecords": [
      ],
    • "domain": "login.example.com",
    • "id": "OcDz6iRyjkaCTXkdo0g3",
    • "publicCertificate": {
      },
    • "validationStatus": "VERIFIED",
    • "_links": {
      }
    }
]
Retrieve the Error Page Sub-Resources
OAuth 2.0: okta.brands.read
Retrieves the error page sub-resources. The expand query parameter specifies which sub-resources to include in the response.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Enum: "default" "customized" "customizedUrl" "preview" "previewUrl"  
Responses 
200
Successfully retrieved the error page.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/pages/error
Request samples 
Response samples 
application/json
{
  • "_embedded": {
    • "default": {
      },
    • "customized": {
      },
    • "customizedUrl": "http://example.com",
    • "preview": {
      },
    • "previewUrl": "http://example.com"
    },
  • "_links": {
    • "self": {
      },
    • "default": {
      },
    • "customized": {
      },
    • "preview": {
      }
    }
}
Retrieve the Customized Error Page
OAuth 2.0: okta.brands.read
Retrieves the customized error page. The customized error page appears in your live environment.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
Successfully retrieved the customized error page.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/pages/error/customized
Request samples 
Response samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    }
}
Replace the Customized Error Page
OAuth 2.0: okta.brands.manage
Replaces the customized error page. The customized error page appears in your live environment.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Request Body schema: application/json
required
pageContent
string
 
object (ContentSecurityPolicySetting) 
 
mode
string
 Enum: "enforced" "report_only"  
reportUri
string
 
srcList
Array of strings
 
Responses 
200
Successfully replaced the customized error page.


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/brands/{brandId}/pages/error/customized
Request samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    }
}
Response samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    }
}
Delete the Customized Error Page
OAuth 2.0: okta.brands.manage
Deletes the customized error page. As a result, the default error page appears in your live environment.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
204
Successfully deleted the customized error page.


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/brands/{brandId}/pages/error/customized
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": [ ]
}
Retrieve the Default Error Page
OAuth 2.0: okta.brands.read
Retrieves the default error page. The default error page appears when no customized error page exists.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
Successfully retrieved the default error page.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/pages/error/default
Request samples 
Response samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    }
}
Retrieve the Preview Error Page Preview
OAuth 2.0: okta.brands.read
Retrieves the preview error page. The preview error page contains unpublished changes and isn't shown in your live environment. Preview it at ${yourOktaDomain}/error/preview.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
Successfully retrieved the preview error page.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/pages/error/preview
Request samples 
Response samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    }
}
Replace the Preview Error Page
OAuth 2.0: okta.brands.manage
Replaces the preview error page. The preview error page contains unpublished changes and isn't shown in your live environment. Preview it at ${yourOktaDomain}/error/preview.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Request Body schema: application/json
required
pageContent
string
 
object (ContentSecurityPolicySetting) 
 
mode
string
 Enum: "enforced" "report_only"  
reportUri
string
 
srcList
Array of strings
 
Responses 
200
Successfully replaced the preview error page.


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/brands/{brandId}/pages/error/preview
Request samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    }
}
Response samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    }
}
Delete the Preview Error Page
OAuth 2.0: okta.brands.manage
Deletes the preview error page. The preview error page contains unpublished changes and isn't shown in your live environment. Preview it at ${yourOktaDomain}/error/preview.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
204
Successfully deleted the preview error page.


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/brands/{brandId}/pages/error/preview
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": [ ]
}
Retrieve the Sign-in Page Sub-Resources
OAuth 2.0: okta.brands.read
Retrieves the sign-in page sub-resources. The expand query parameter specifies which sub-resources to include in the response.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Enum: "default" "customized" "customizedUrl" "preview" "previewUrl"  
Responses 
200
Successfully retrieved the sign-in page.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/pages/sign-in
Request samples 
Response samples 
application/json
{
  • "_embedded": {
    • "default": {
      },
    • "customized": {
      },
    • "customizedUrl": "http://example.com",
    • "preview": {
      },
    • "previewUrl": "http://example.com"
    },
  • "_links": {
    • "self": {
      },
    • "default": {
      },
    • "customized": {
      },
    • "preview": {
      }
    }
}
Retrieve the Customized Sign-in Page
OAuth 2.0: okta.brands.read
Retrieves the customized sign-in page. The customized sign-in page appears in your live environment.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
Successfully retrieved the customized sign-in page.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/pages/sign-in/customized
Request samples 
Response samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    },
  • "widgetCustomizations": {
    • "signInLabel": "string",
    • "usernameLabel": "string",
    • "usernameInfoTip": "string",
    • "passwordLabel": "string",
    • "passwordInfoTip": "string",
    • "showPasswordVisibilityToggle": true,
    • "showUserIdentifier": true,
    • "forgotPasswordLabel": "string",
    • "forgotPasswordUrl": "string",
    • "unlockAccountLabel": "string",
    • "unlockAccountUrl": "string",
    • "helpLabel": "string",
    • "helpUrl": "string",
    • "customLink1Label": "string",
    • "customLink1Url": "string",
    • "customLink2Label": "string",
    • "customLink2Url": "string",
    • "authenticatorPageCustomLinkLabel": "string",
    • "authenticatorPageCustomLinkUrl": "string",
    • "classicRecoveryFlowEmailOrUsernameLabel": "string",
    • "widgetGeneration": "G2"
    },
  • "widgetVersion": "string"
}
Replace the Customized Sign-in Page
OAuth 2.0: okta.brands.manage
Replaces the customized sign-in page. The customized sign-in page appears in your live environment.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Request Body schema: application/json
required
pageContent
string
 
object (ContentSecurityPolicySetting) 
 
mode
string
 Enum: "enforced" "report_only"  
reportUri
string
 
srcList
Array of strings
 
object
 
signInLabel
string
 
usernameLabel
string
 
usernameInfoTip
string
 
passwordLabel
string
 
passwordInfoTip
string
 
showPasswordVisibilityToggle
boolean
 
showUserIdentifier
boolean
 
forgotPasswordLabel
string
 
forgotPasswordUrl
string
 
unlockAccountLabel
string
 
unlockAccountUrl
string
 
helpLabel
string
 
helpUrl
string
 
customLink1Label
string
 
customLink1Url
string
 
customLink2Label
string
 
customLink2Url
string
 
authenticatorPageCustomLinkLabel
string
 
authenticatorPageCustomLinkUrl
string
 
classicRecoveryFlowEmailOrUsernameLabel
string
 
widgetGeneration
string (WidgetGeneration) 
 Enum: "G2" "G3"  
widgetVersion
string (Version) ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...
The version specified as a Semantic Version.


 
Responses 
200
Successfully replaced the customized sign-in page.


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/brands/{brandId}/pages/sign-in/customized
Request samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    },
  • "widgetCustomizations": {
    • "signInLabel": "string",
    • "usernameLabel": "string",
    • "usernameInfoTip": "string",
    • "passwordLabel": "string",
    • "passwordInfoTip": "string",
    • "showPasswordVisibilityToggle": true,
    • "showUserIdentifier": true,
    • "forgotPasswordLabel": "string",
    • "forgotPasswordUrl": "string",
    • "unlockAccountLabel": "string",
    • "unlockAccountUrl": "string",
    • "helpLabel": "string",
    • "helpUrl": "string",
    • "customLink1Label": "string",
    • "customLink1Url": "string",
    • "customLink2Label": "string",
    • "customLink2Url": "string",
    • "authenticatorPageCustomLinkLabel": "string",
    • "authenticatorPageCustomLinkUrl": "string",
    • "classicRecoveryFlowEmailOrUsernameLabel": "string",
    • "widgetGeneration": "G2"
    },
  • "widgetVersion": "string"
}
Response samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    },
  • "widgetCustomizations": {
    • "signInLabel": "string",
    • "usernameLabel": "string",
    • "usernameInfoTip": "string",
    • "passwordLabel": "string",
    • "passwordInfoTip": "string",
    • "showPasswordVisibilityToggle": true,
    • "showUserIdentifier": true,
    • "forgotPasswordLabel": "string",
    • "forgotPasswordUrl": "string",
    • "unlockAccountLabel": "string",
    • "unlockAccountUrl": "string",
    • "helpLabel": "string",
    • "helpUrl": "string",
    • "customLink1Label": "string",
    • "customLink1Url": "string",
    • "customLink2Label": "string",
    • "customLink2Url": "string",
    • "authenticatorPageCustomLinkLabel": "string",
    • "authenticatorPageCustomLinkUrl": "string",
    • "classicRecoveryFlowEmailOrUsernameLabel": "string",
    • "widgetGeneration": "G2"
    },
  • "widgetVersion": "string"
}
Delete the Customized Sign-in Page
OAuth 2.0: okta.brands.manage
Deletes the customized sign-in page. As a result, the default sign-in page appears in your live environment.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
204
Successfully deleted the sign-in page.


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/brands/{brandId}/pages/sign-in/customized
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": [ ]
}
Retrieve the Default Sign-in Page
OAuth 2.0: okta.brands.read
Retrieves the default sign-in page. The default sign-in page appears when no customized sign-in page exists.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
Successfully retrieved the default sign-in page.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/pages/sign-in/default
Request samples 
Response samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    },
  • "widgetCustomizations": {
    • "signInLabel": "string",
    • "usernameLabel": "string",
    • "usernameInfoTip": "string",
    • "passwordLabel": "string",
    • "passwordInfoTip": "string",
    • "showPasswordVisibilityToggle": true,
    • "showUserIdentifier": true,
    • "forgotPasswordLabel": "string",
    • "forgotPasswordUrl": "string",
    • "unlockAccountLabel": "string",
    • "unlockAccountUrl": "string",
    • "helpLabel": "string",
    • "helpUrl": "string",
    • "customLink1Label": "string",
    • "customLink1Url": "string",
    • "customLink2Label": "string",
    • "customLink2Url": "string",
    • "authenticatorPageCustomLinkLabel": "string",
    • "authenticatorPageCustomLinkUrl": "string",
    • "classicRecoveryFlowEmailOrUsernameLabel": "string",
    • "widgetGeneration": "G2"
    },
  • "widgetVersion": "string"
}
Retrieve the Preview Sign-in Page Preview
OAuth 2.0: okta.brands.read
Retrieves the preview sign-in page. The preview sign-in page contains unpublished changes and isn't shown in your live environment. Preview it at ${yourOktaDomain}/login/preview.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
Successfully retrieved the preview sign-in page.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/pages/sign-in/preview
Request samples 
Response samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    },
  • "widgetCustomizations": {
    • "signInLabel": "string",
    • "usernameLabel": "string",
    • "usernameInfoTip": "string",
    • "passwordLabel": "string",
    • "passwordInfoTip": "string",
    • "showPasswordVisibilityToggle": true,
    • "showUserIdentifier": true,
    • "forgotPasswordLabel": "string",
    • "forgotPasswordUrl": "string",
    • "unlockAccountLabel": "string",
    • "unlockAccountUrl": "string",
    • "helpLabel": "string",
    • "helpUrl": "string",
    • "customLink1Label": "string",
    • "customLink1Url": "string",
    • "customLink2Label": "string",
    • "customLink2Url": "string",
    • "authenticatorPageCustomLinkLabel": "string",
    • "authenticatorPageCustomLinkUrl": "string",
    • "classicRecoveryFlowEmailOrUsernameLabel": "string",
    • "widgetGeneration": "G2"
    },
  • "widgetVersion": "string"
}
Replace the Preview Sign-in Page
OAuth 2.0: okta.brands.manage
Replaces the preview sign-in page. The preview sign-in page contains unpublished changes and isn't shown in your live environment. Preview it at ${yourOktaDomain}/login/preview.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Request Body schema: application/json
required
pageContent
string
 
object (ContentSecurityPolicySetting) 
 
mode
string
 Enum: "enforced" "report_only"  
reportUri
string
 
srcList
Array of strings
 
object
 
signInLabel
string
 
usernameLabel
string
 
usernameInfoTip
string
 
passwordLabel
string
 
passwordInfoTip
string
 
showPasswordVisibilityToggle
boolean
 
showUserIdentifier
boolean
 
forgotPasswordLabel
string
 
forgotPasswordUrl
string
 
unlockAccountLabel
string
 
unlockAccountUrl
string
 
helpLabel
string
 
helpUrl
string
 
customLink1Label
string
 
customLink1Url
string
 
customLink2Label
string
 
customLink2Url
string
 
authenticatorPageCustomLinkLabel
string
 
authenticatorPageCustomLinkUrl
string
 
classicRecoveryFlowEmailOrUsernameLabel
string
 
widgetGeneration
string (WidgetGeneration) 
 Enum: "G2" "G3"  
widgetVersion
string (Version) ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...
The version specified as a Semantic Version.


 
Responses 
200
Successfully replaced the preview sign-in page.


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/brands/{brandId}/pages/sign-in/preview
Request samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    },
  • "widgetCustomizations": {
    • "signInLabel": "string",
    • "usernameLabel": "string",
    • "usernameInfoTip": "string",
    • "passwordLabel": "string",
    • "passwordInfoTip": "string",
    • "showPasswordVisibilityToggle": true,
    • "showUserIdentifier": true,
    • "forgotPasswordLabel": "string",
    • "forgotPasswordUrl": "string",
    • "unlockAccountLabel": "string",
    • "unlockAccountUrl": "string",
    • "helpLabel": "string",
    • "helpUrl": "string",
    • "customLink1Label": "string",
    • "customLink1Url": "string",
    • "customLink2Label": "string",
    • "customLink2Url": "string",
    • "authenticatorPageCustomLinkLabel": "string",
    • "authenticatorPageCustomLinkUrl": "string",
    • "classicRecoveryFlowEmailOrUsernameLabel": "string",
    • "widgetGeneration": "G2"
    },
  • "widgetVersion": "string"
}
Response samples 
application/json
{
  • "pageContent": "string",
  • "contentSecurityPolicySetting": {
    • "mode": "enforced",
    • "reportUri": "string",
    • "srcList": [
      ]
    },
  • "widgetCustomizations": {
    • "signInLabel": "string",
    • "usernameLabel": "string",
    • "usernameInfoTip": "string",
    • "passwordLabel": "string",
    • "passwordInfoTip": "string",
    • "showPasswordVisibilityToggle": true,
    • "showUserIdentifier": true,
    • "forgotPasswordLabel": "string",
    • "forgotPasswordUrl": "string",
    • "unlockAccountLabel": "string",
    • "unlockAccountUrl": "string",
    • "helpLabel": "string",
    • "helpUrl": "string",
    • "customLink1Label": "string",
    • "customLink1Url": "string",
    • "customLink2Label": "string",
    • "customLink2Url": "string",
    • "authenticatorPageCustomLinkLabel": "string",
    • "authenticatorPageCustomLinkUrl": "string",
    • "classicRecoveryFlowEmailOrUsernameLabel": "string",
    • "widgetGeneration": "G2"
    },
  • "widgetVersion": "string"
}
Delete the Preview Sign-in Page
OAuth 2.0: okta.brands.manage
Deletes the preview sign-in page. The preview sign-in page contains unpublished changes and isn't shown in your live environment. Preview it at ${yourOktaDomain}/login/preview.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
204
Successfully deleted the preview sign-in page.


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/brands/{brandId}/pages/sign-in/preview
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": [ ]
}
List all Sign-in Widget Versions
OAuth 2.0: okta.brands.read
Lists all sign-in widget versions supported by the current org


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
Successfully listed the sign-in widget versions.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/pages/sign-in/widget-versions
Request samples 
Response samples 
application/json
[
  • "string"
]
Retrieve the Sign-out Page Settings
OAuth 2.0: okta.brands.read
Retrieves the sign-out page settings


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
Successfully retrieved the sign-out page settings.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/pages/sign-out/customized
Request samples 
Response samples 
application/json
{
  • "type": "EXTERNALLY_HOSTED",
  • "url": "string"
}
Replace the Sign-out Page Settings
OAuth 2.0: okta.brands.manage
Replaces the sign-out page settings


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Request Body schema: application/json
required
type
required
string (HostedPageType) 
 Enum: "EXTERNALLY_HOSTED" "OKTA_DEFAULT"  
url
string
 
Responses 
200
Successfully replaced the sign-out page settings.


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/brands/{brandId}/pages/sign-out/customized
Request samples 
application/json
{
  • "type": "EXTERNALLY_HOSTED",
  • "url": "string"
}
Response samples 
application/json
{
  • "type": "EXTERNALLY_HOSTED",
  • "url": "string"
}
List all Email Templates
OAuth 2.0: okta.templates.read
Lists all email templates


Request 
path Parameters
brandId
required
string
The ID of the brand


 
query Parameters
after
string
The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.


 
limit
integer  [ 1 .. 200 ] 
 Default:  20
A limit on the number of objects to return


 
expand
Array of strings
Specifies additional metadata to be included in the response


Items Enum: "settings" "customizationCount"  
Responses 
200
Successfully returned the list of email templates.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email
Request samples 
Response samples 
application/json
[]
Retrieve an Email Template
OAuth 2.0: okta.templates.read
Retrieves the details of an email template by name


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
query Parameters
expand
Array of strings
Specifies additional metadata to be included in the response


Items Enum: "settings" "customizationCount"  
Responses 
200
Successfully retrieved the email template.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}
Request samples 
Response samples 
application/json
{}
List all Email Customizations
OAuth 2.0: okta.templates.read
Lists all customizations of an email template


 If Custom languages for Okta Email Templates is enabled, all existing customizations are retrieved, including customizations for additional languages. If disabled, only customizations for Okta-supported languages are returned.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
query Parameters
after
string
The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.


 
limit
integer  [ 1 .. 200 ] 
 Default:  20
A limit on the number of objects to return


 
Responses 
200
Successfully retrieved all email customizations for the specified email template.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/customizations
Request samples 
Response samples 
application/json
[]
Create an Email Customization
OAuth 2.0: okta.templates.manage
Creates a new Email Customization


 If Custom languages for Okta Email Templates is enabled, you can create a customization for any BCP47 language in addition to the Okta-supported languages.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
Request Body schema: application/json
body
required
string
The HTML body of the email. May contain variable references. 


 Not required if Custom languages for Okta Email Templates is enabled. A null body is replaced with a default value from one of the following in priority order:


    

  1. An existing default email customization, if one exists
    2. 

  2. Okta-provided translated content for the specified language, if one exists
    3. 

  3. Okta-provided translated content for the brand locale, if it's set 
    4. 

  4. Okta-provided content in English
    5. 



 
subject
required
string
The email subject. May contain variable references.


 Not required if Custom languages for Okta Email Templates is enabled. A null subject is replaced with a default value from one of the following in priority order:


    

  1. An existing default email customization, if one exists
    2. 

  2. Okta-provided translated content for the specified language, if one exists
    3. 

  3. Okta-provided translated content for the brand locale, if it's set
    4. 

  4. Okta-provided content in English
    5. 



 
isDefault
boolean
Whether this is the default customization for the email template. Each customized email template must have exactly one default customization. Defaults to true for the first customization and false thereafter.


 
language
required
string (Language) 
The language specified as an IETF BCP 47 language tag


 
Responses 
201
Successfully created the email customization.


400
Bad Request


403
Forbidden


404
Not Found


409
Could not create the email customization because it conflicts with an existing email customization.


429
Too Many Requests


post/api/v1/brands/{brandId}/templates/email/{templateName}/customizations
Request samples 
application/json
{
  • "language": "fr",
  • "subject": "Bienvenue dans ${org.name}!",
  • "body": "<!DOCTYPE html><html><body><p>Bonjour ${user.profile.firstName}. <a href=\"${activationLink}\">Activer le compte</a></p></body></html>",
  • "isDefault": false
}
Response samples 
application/json
{}
Delete all Email Customizations
OAuth 2.0: okta.templates.manage
Deletes all customizations for an email template


 If Custom languages for Okta Email Templates is enabled, all customizations are deleted, including customizations for additional languages. If disabled, only customizations in Okta-supported languages are deleted.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
Responses 
204
Successfully deleted all customizations for the email template.


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/brands/{brandId}/templates/email/{templateName}/customizations
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": [ ]
}
Retrieve an Email Customization
OAuth 2.0: okta.templates.read
Retrieves an email customization by its unique identifier


 If Custom languages for Okta Email Templates is disabled, requests to retrieve an additional language customization by ID result in a 404 Not Found error response.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
customizationId
required
string
The ID of the email customization


 
Responses 
200
Successfully retrieved the email customization.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/customizations/{customizationId}
Request samples 
Response samples 
application/json
{}
Replace an Email Customization
OAuth 2.0: okta.templates.manage
Replaces an email customization using property values


 If Custom languages for Okta Email Templates is disabled, requests to update a customization for an additional language return a 404 Not Found error response.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
customizationId
required
string
The ID of the email customization


 
Request Body schema: application/json
Request


body
required
string
The HTML body of the email. May contain variable references. 


 Not required if Custom languages for Okta Email Templates is enabled. A null body is replaced with a default value from one of the following in priority order:


    

  1. An existing default email customization, if one exists
    2. 

  2. Okta-provided translated content for the specified language, if one exists
    3. 

  3. Okta-provided translated content for the brand locale, if it's set 
    4. 

  4. Okta-provided content in English
    5. 



 
subject
required
string
The email subject. May contain variable references.


 Not required if Custom languages for Okta Email Templates is enabled. A null subject is replaced with a default value from one of the following in priority order:


    

  1. An existing default email customization, if one exists
    2. 

  2. Okta-provided translated content for the specified language, if one exists
    3. 

  3. Okta-provided translated content for the brand locale, if it's set
    4. 

  4. Okta-provided content in English
    5. 



 
isDefault
boolean
Whether this is the default customization for the email template. Each customized email template must have exactly one default customization. Defaults to true for the first customization and false thereafter.


 
language
required
string (Language) 
The language specified as an IETF BCP 47 language tag


 
Responses 
200
Successfully updated the email customization.


400
Bad Request


403
Forbidden


404
Not Found


409
Could not update the email customization because the update would cause a conflict with an existing email customization.


429
Too Many Requests


put/api/v1/brands/{brandId}/templates/email/{templateName}/customizations/{customizationId}
Request samples 
application/json
{
  • "language": "fr",
  • "subject": "Bienvenue dans ${org.name}!",
  • "body": "<!DOCTYPE html><html><body><p>Bonjour ${user.profile.firstName}. <a href=\"${activationLink}\">Activer le compte</a></p></body></html>",
  • "isDefault": false
}
Response samples 
application/json
{}
Delete an Email Customization
OAuth 2.0: okta.templates.manage
Deletes an Email Customization by its unique identifier


 If Custom languages for Okta Email Templates is disabled, deletion of an existing additional language customization by ID doesn't register.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
customizationId
required
string
The ID of the email customization


 
Responses 
204
Successfully deleted the email customization.


403
Forbidden


404
Not Found


409
Could not delete the email customization deleted because it is the default email customization.


429
Too Many Requests


delete/api/v1/brands/{brandId}/templates/email/{templateName}/customizations/{customizationId}
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": [ ]
}
Retrieve a Preview of an Email Customization
OAuth 2.0: okta.templates.read
Retrieves a Preview of an Email Customization. All variable references are populated from the current user's context. For example, ${user.profile.firstName}.


 If Custom languages for Okta Email Templates is disabled, requests for the preview of an additional language customization by ID return a 404 Not Found error response.


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
customizationId
required
string
The ID of the email customization


 
Responses 
200
Successfully generated a preview of the email customization.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/customizations/{customizationId}/preview
Request samples 
Response samples 
application/json
{}
Retrieve an Email Template Default Content
OAuth 2.0: okta.templates.read
Retrieves an email template's default content


 Defaults to the current user's language given the following: 


    

  • Custom languages for Okta Email Templates is enabled
    • 

  • An additional language is specified for the language parameter
    • 



Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
query Parameters
language
string (Language) 
The language to use for the email. Defaults to the current user's language if unspecified.


 
Responses 
200
Successfully retrieved the email template's default content.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/default-content
Request samples 
Response samples 
application/json
{}
Retrieve a Preview of the Email Template default content
OAuth 2.0: okta.templates.read
Retrieves a preview of an Email Template's default content. All variable references are populated using the current user's context. For example, ${user.profile.firstName}.


 Defaults to the current user's language given the following:


    

  • Custom languages for Okta Email Templates is enabled
    • 

  • An additional language is specified for the language parameter
    • 



Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
query Parameters
language
string (Language) 
The language to use for the email. Defaults to the current user's language if unspecified.


 
Responses 
200
Successfully generated a preview of the email template's default content.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/default-content/preview
Request samples 
Response samples 
application/json
{}
Retrieve the Email Template Settings
OAuth 2.0: okta.templates.read
Retrieves an email template's settings


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
Responses 
200
Successfully retrieved the email template's settings.


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/templates/email/{templateName}/settings
Request samples 
Response samples 
application/json
{}
Replace the Email Template Settings
OAuth 2.0: okta.templates.manage
Replaces an email template's settings


Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
Request Body schema: application/json
recipients
required
string
 Enum: "ALL_USERS" "ADMINS_ONLY" "NO_USERS"  
Responses 
204
Successfully updated the email template's settings.


400
Bad Request


403
Forbidden


404
Not Found


422
Could not update the email template's settings due to an invalid setting value.


429
Too Many Requests


put/api/v1/brands/{brandId}/templates/email/{templateName}/settings
Request samples 
application/json
{
  • "recipients": "ALL_USERS"
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Send a Test Email
OAuth 2.0: okta.templates.read
Sends a test email to the current user’s primary and secondary email addresses. The email content is selected based on the following priority:


    

  1. The email customization for the language specified in the language query parameter.
 If Custom languages for Okta Email Templates is enabled and the language parameter is an additional language, the test email uses the customization corresponding to the language.
    2. 

  2. The email template's default customization.
    3. 

  3. The email template’s default content, translated to the current user's language.
    4. 



Request 
path Parameters
brandId
required
string
The ID of the brand


 
templateName
required
string
The name of the email template


 
query Parameters
language
string (Language) 
The language to use for the email. Defaults to the current user's language if unspecified.


 
Responses 
204
Successfully sent a test email.


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/brands/{brandId}/templates/email/{templateName}/test
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": [ ]
}
List all Themes
OAuth 2.0: okta.brands.read
Lists all the themes in your brand


Request 
path Parameters
brandId
required
string
The ID of the brand


 
Responses 
200
OK


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/themes
Request samples 
Response samples 
application/json
[
  • {
    • "backgroundImage": "string",
    • "emailTemplateTouchPointVariant": "FULL_THEME",
    • "endUserDashboardTouchPointVariant": "FULL_THEME",
    • "errorPageTouchPointVariant": "BACKGROUND_IMAGE",
    • "favicon": "string",
    • "id": "string",
    • "loadingPageTouchPointVariant": "NONE",
    • "logo": "string",
    • "primaryColorContrastHex": "string",
    • "primaryColorHex": "string",
    • "secondaryColorContrastHex": "string",
    • "secondaryColorHex": "string",
    • "signInPageTouchPointVariant": "BACKGROUND_IMAGE",
    • "_links": {
      }
    }
]
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
OK


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/brands/{brandId}/themes/{themeId}
Request samples 
Response samples 
application/json
{
  • "backgroundImage": "string",
  • "emailTemplateTouchPointVariant": "FULL_THEME",
  • "endUserDashboardTouchPointVariant": "FULL_THEME",
  • "errorPageTouchPointVariant": "BACKGROUND_IMAGE",
  • "favicon": "string",
  • "id": "string",
  • "loadingPageTouchPointVariant": "NONE",
  • "logo": "string",
  • "primaryColorContrastHex": "string",
  • "primaryColorHex": "string",
  • "secondaryColorContrastHex": "string",
  • "secondaryColorHex": "string",
  • "signInPageTouchPointVariant": "BACKGROUND_IMAGE",
  • "_links": {
    • "self": {
      }
    }
}
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
emailTemplateTouchPointVariant
string (EmailTemplateTouchPointVariant) 
 Enum: "FULL_THEME" "OKTA_DEFAULT"  
endUserDashboardTouchPointVariant
string (EndUserDashboardTouchPointVariant) 
 Enum: "FULL_THEME" "LOGO_ON_FULL_WHITE_BACKGROUND" "OKTA_DEFAULT" "WHITE_LOGO_BACKGROUND"  
errorPageTouchPointVariant
string (ErrorPageTouchPointVariant) 
 Enum: "BACKGROUND_IMAGE" "BACKGROUND_SECONDARY_COLOR" "OKTA_DEFAULT"  
loadingPageTouchPointVariant
string (LoadingPageTouchPointVariant) 
 Enum: "NONE" "OKTA_DEFAULT"  
primaryColorContrastHex
string
 
primaryColorHex
string
 
secondaryColorContrastHex
string
 
secondaryColorHex
string
 
signInPageTouchPointVariant
string (SignInPageTouchPointVariant) 
 Enum: "BACKGROUND_IMAGE" "BACKGROUND_SECONDARY_COLOR" "OKTA_DEFAULT"  
Responses 
200
OK


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/brands/{brandId}/themes/{themeId}
Request samples 
application/json
{
  • "emailTemplateTouchPointVariant": "FULL_THEME",
  • "endUserDashboardTouchPointVariant": "FULL_THEME",
  • "errorPageTouchPointVariant": "BACKGROUND_IMAGE",
  • "loadingPageTouchPointVariant": "NONE",
  • "primaryColorContrastHex": "string",
  • "primaryColorHex": "string",
  • "secondaryColorContrastHex": "string",
  • "secondaryColorHex": "string",
  • "signInPageTouchPointVariant": "BACKGROUND_IMAGE"
}
Response samples 
application/json
{
  • "backgroundImage": "string",
  • "emailTemplateTouchPointVariant": "FULL_THEME",
  • "endUserDashboardTouchPointVariant": "FULL_THEME",
  • "errorPageTouchPointVariant": "BACKGROUND_IMAGE",
  • "favicon": "string",
  • "id": "string",
  • "loadingPageTouchPointVariant": "NONE",
  • "logo": "string",
  • "primaryColorContrastHex": "string",
  • "primaryColorHex": "string",
  • "secondaryColorContrastHex": "string",
  • "secondaryColorHex": "string",
  • "signInPageTouchPointVariant": "BACKGROUND_IMAGE",
  • "_links": {
    • "self": {
      }
    }
}
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
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": [ ]
}