Custom Pages

These endpoints allow you to customize the contents of various pages, including:

  • The Okta-hosted sign-in page
  • Error pages
  • The sign-out page

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using 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.

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
The HTML for the page


 
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
The HTML for the page


 
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
The HTML for the page


 
object (ContentSecurityPolicySetting) 
 
mode
string
 Enum: "enforced" "report_only"  
reportUri
string
 
srcList
Array of strings
 
object
 
signInLabel
string
The label for the sign in widget


 
usernameLabel
string
The label for the username field


 
usernameInfoTip
string
The label for the username information tip


 
passwordLabel
string
The label for the password field


 
passwordInfoTip
string
The label for the password information tip


 
showPasswordVisibilityToggle
boolean
Allows users to see their passwords as they type


 
showUserIdentifier
boolean
Allows the user's identifier to appear on authentication and enrollment pages


 
forgotPasswordLabel
string
The label for the forgot password page


 
forgotPasswordUrl
string
The forgot password URL


 
unlockAccountLabel
string
The label for the unlock account link


 
unlockAccountUrl
string
The unlock account URL


 
helpLabel
string
The label for the help link


 
helpUrl
string
The help link URL


 
customLink1Label
string
The label for the first custom link


 
customLink1Url
string
The URL for the first custom link


 
customLink2Label
string
The label for the second custom link


 
customLink2Url
string
The URL for the second custom link


 
authenticatorPageCustomLinkLabel
string
The label for the authenticator page custom link


 
authenticatorPageCustomLinkUrl
string
The URL for the authenticator page custom link


 
classicRecoveryFlowEmailOrUsernameLabel
string
The label for the username field in the classic recovery flow


 
widgetGeneration
string (WidgetGeneration) 
The generation of the Sign-in Widget


 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
The HTML for the page


 
object (ContentSecurityPolicySetting) 
 
mode
string
 Enum: "enforced" "report_only"  
reportUri
string
 
srcList
Array of strings
 
object
 
signInLabel
string
The label for the sign in widget


 
usernameLabel
string
The label for the username field


 
usernameInfoTip
string
The label for the username information tip


 
passwordLabel
string
The label for the password field


 
passwordInfoTip
string
The label for the password information tip


 
showPasswordVisibilityToggle
boolean
Allows users to see their passwords as they type


 
showUserIdentifier
boolean
Allows the user's identifier to appear on authentication and enrollment pages


 
forgotPasswordLabel
string
The label for the forgot password page


 
forgotPasswordUrl
string
The forgot password URL


 
unlockAccountLabel
string
The label for the unlock account link


 
unlockAccountUrl
string
The unlock account URL


 
helpLabel
string
The label for the help link


 
helpUrl
string
The help link URL


 
customLink1Label
string
The label for the first custom link


 
customLink1Url
string
The URL for the first custom link


 
customLink2Label
string
The label for the second custom link


 
customLink2Url
string
The URL for the second custom link


 
authenticatorPageCustomLinkLabel
string
The label for the authenticator page custom link


 
authenticatorPageCustomLinkUrl
string
The URL for the authenticator page custom link


 
classicRecoveryFlowEmailOrUsernameLabel
string
The label for the username field in the classic recovery flow


 
widgetGeneration
string (WidgetGeneration) 
The generation of the Sign-in Widget


 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"
}