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

The HTML for the page

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