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. Okta-provided translated content for the specified language, if one exists
  3. Okta-provided translated content for the brand locale, if it's set
  4. Okta-provided content in English
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. Okta-provided translated content for the specified language, if one exists
  3. Okta-provided translated content for the brand locale, if it's set
  4. Okta-provided content in English
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
{}