Important Multibrand customization updates are available in our new API reference docs. See Customizations (opens new window).

Brands API

The Okta Brands API allows you to customize the look and feel of pages and templates, including:

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

Each org starts off with Okta default branding. You can upload your own assets (colors, background image, logo, and favicon) to replace Okta default brand assets. You can then publish these assets directly to your pages and templates.

Get started

Explore the Brands API: (opens new window)

Brand operations

The Brands API has the following CRUD operations:

• Get Brands
• Get Brand
• Update Brand

Get Brands

GET /api/v1/brands

List all the brands in your org

Response body

Array of the Brand Response

Important: Currently Okta only supports one Brand per org, therefore this contains a single object only.

Use examples

The following example returns all Brands in the org.

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands"

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "bndul904tTZ6kWVhP0g3",
    "customPrivacyPolicyUrl": null,
    "removePoweredByOkta": false,
    "_links": {
      "themes": {
        "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes",
        "hints": {
          "allow": [
            "GET"
          ]
        }
      },
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      }
    }
  }
]

Get Brand

GET /api/v1/brands/${brandId}

Fetches a brand by brandId

Request path parameters

Parameter	Type	Description
brandId	String (URL)	ID of a Brand

Response body

The requested Brand Response

Passing an invalid brandId returns a 404 Not Found status code with the error code E0000007.

Use examples

The following example returns a Brand object by ID:

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}"

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "bndul904tTZ6kWVhP0g3",
  "customPrivacyPolicyUrl": null,
  "removePoweredByOkta": false,
  "_links": {
    "themes": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    }
  }
}

Update Brand

PUT /api/v1/brands/${brandId}

Updates a Brand by brandId

Request path parameters

Parameter	Type	Description
brandId	String (URL)	ID of a Brand

Request body

The Brand

Response body

Returns an updated Brand Response

Passing an invalid brandId returns a 404 Not Found status code with the error code E0000007.

Not providing agreeToCustomPrivacyPolicy with customPrivacyPolicyUrl returns a 400 Bad Request status code with the error code E0000001.

The removePoweredByOkta parameter is optional. Default value is false.

Use examples

The following example updates a custom privacy policy URL.

Request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "agreeToCustomPrivacyPolicy": true,
  "customPrivacyPolicyUrl": "https://www.someHost.com/privacy-policy"
}' "https://${yourOktaDomain}/api/v1/brands/${brandId}"

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "bndul904tTZ6kWVhP0g3",
  "customPrivacyPolicyUrl": "https://www.someHost.com/privacy-policy",
  "removePoweredByOkta": false,
  "_links": {
    "themes": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    }
  }
}

The following example does the following:

• Resets a privacy policy URL to use the Okta default privacy policy URL
• Removes "Powered by Okta" from the Okta-hosted sign-in page
• Removes "© 2021 Okta, Inc." from the Okta End-User Dashboard

Request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "customPrivacyPolicyUrl": null,
  "removePoweredByOkta": true
}' "https://${yourOktaDomain}/api/v1/brands/${brandId}"

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "bndul904tTZ6kWVhP0g3",
  "customPrivacyPolicyUrl": null,
  "removePoweredByOkta": true,
  "_links": {
    "themes": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    }
  }
}

The following example shows invalid URL validation.

Request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "customPrivacyPolicyUrl": "randomValue"
}' "https://${yourOktaDomain}/api/v1/brands/${brandId}"

Response

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: customPrivacyPolicyUrl",
  "errorLink": "E0000001",
  "errorId": "oaeqEUQ0u06QrO-0rDPpz3j6w",
  "errorCauses": [
    {
      "errorSummary": "customPrivacyPolicyUrl: Is not a valid URL. Valid example: http://www.okta.com"
    }
  ]
}

The following example shows consent-required validation.

Request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "customPrivacyPolicyUrl": "https://www.someHost.com/privacy-policy"
}' "https://${yourOktaDomain}/api/v1/brands/${brandId}"

Response

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: agreeToCustomPrivacyPolicy",
  "errorLink": "E0000001",
  "errorId": "oae3uLW0D8wTwmiVdZokrnpAA",
  "errorCauses": [
    {
      "errorSummary": "agreeToCustomPrivacyPolicy: Please provide your consent for updating the custom privacy policy URL."
    }
  ]
}

Themes operations

The Themes API has the following CRUD operations:

• Get Themes
• Get Theme
• Update Theme
• Upload Theme logo
• Delete Theme logo
• Upload Theme favicon
• Delete Theme favicon
• Upload Theme background image
• Delete Theme background image

Get Themes

GET /api/v1/brands/${brandId}/themes

List all the themes in your brand

Request path parameters

Parameter	Type	Description
brandId	String (URL)	ID of a Brand

Response body

Array of the Theme Response

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

Passing an invalid brandId returns a 404 Not Found status code with the error code E0000007.

Use examples

The following example returns all the Themes in the Brand.

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes"

Response

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "thdul904tTZ6kWVhP0g3",
    "logo": "https://{yourOktaDomain}/assets/img/logos/okta-logo.47066819ac7db5c13f4c431b2687cef6.png",
    "favicon": "https://{yourOktaDomain}/favicon.ico",
    "backgroundImage": null,
    "primaryColorHex": "#1662dd",
    "primaryColorContrastHex": "#000000",
    "secondaryColorHex": "#ebebed",
    "secondaryColorContrastHex": "#000000",
    "signInPageTouchPointVariant": "OKTA_DEFAULT",
    "endUserDashboardTouchPointVariant": "OKTA_DEFAULT",
    "errorPageTouchPointVariant": "OKTA_DEFAULT",
    "emailTemplateTouchPointVariant": "OKTA_DEFAULT",
    "loadingPageTouchPointVariant": "OKTA_DEFAULT",
    "_links": {
      "favicon": {
        "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/favicon",
        "hints": {
          "allow": [
            "POST",
            "DELETE"
          ]
        }
      },
      "self": {
        "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3",
        "hints": {
          "allow": [
            "GET",
            "PUT"
          ]
        }
      },
      "logo": {
        "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/logo",
        "hints": {
          "allow": [
            "POST",
            "DELETE"
          ]
        }
      },
      "background-image": {
        "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/background-image",
        "hints": {
          "allow": [
            "POST",
            "DELETE"
          ]
        }
      }
    }
  }
]

Get Theme

GET /api/v1/brands/${brandId}/themes/${themeId}

Fetches a Theme for a Brand

Request path parameters

Parameter	Type	Description
brandId	String (URL)	ID of a Brand
themeId	String (URL)	ID of a Theme

Response body

The requested Theme Response

Passing an invalid brandId or an invalid themeId returns a 404 Not Found status code with the error code E0000007.

Use examples

The following example returns a Theme object:

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}"

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "thdul904tTZ6kWVhP0g3",
  "logo": "https://{yourOktaDomain}/assets/img/logos/okta-logo.47066819ac7db5c13f4c431b2687cef6.png",
  "favicon": "https://{yourOktaDomain}/favicon.ico",
  "backgroundImage": null,
  "primaryColorHex": "#1662dd",
  "primaryColorContrastHex": "#000000",
  "secondaryColorHex": "#ebebed",
  "secondaryColorContrastHex": "#000000",
  "signInPageTouchPointVariant": "OKTA_DEFAULT",
  "endUserDashboardTouchPointVariant": "OKTA_DEFAULT",
  "errorPageTouchPointVariant": "OKTA_DEFAULT",
  "emailTemplateTouchPointVariant": "OKTA_DEFAULT",
  "loadingPageTouchPointVariant": "OKTA_DEFAULT",
  "_links": {
    "favicon": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/favicon",
      "hints": {
        "allow": [
          "POST",
          "DELETE"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    },
    "logo": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/logo",
      "hints": {
        "allow": [
          "POST",
          "DELETE"
        ]
      }
    },
    "background-image": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/background-image",
      "hints": {
        "allow": [
          "POST",
          "DELETE"
        ]
      }
    }
  }
}

Update Theme

PUT /api/v1/brands/${brandId}/themes/${themeId}

Updates a Theme for a Brand

Request path parameters

Parameter	Type	Description
brandId	String (URL)	ID of a Brand
themeId	String (URL)	ID of a Theme

Request body

The Theme

Response body

Returns an updated Theme Response

• Passing an invalid brandId or an invalid themeId returns a 404 Not Found status code with the error code E0000007.

• Passing invalid body parameters returns a 400 Bad Request status code with the error code E0000001.

Use examples

The following example updates Theme properties.

Request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "primaryColorHex": "#1662dd",
    "secondaryColorHex": "#ebebed",
    "signInPageTouchPointVariant": "OKTA_DEFAULT",
    "endUserDashboardTouchPointVariant": "OKTA_DEFAULT",
    "errorPageTouchPointVariant": "OKTA_DEFAULT",
    "emailTemplateTouchPointVariant": "OKTA_DEFAULT",
    "loadingPageTouchPointVariant": "OKTA_DEFAULT"
}' "https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}"

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "thdul904tTZ6kWVhP0g3",
  "logo": "https://{yourOktaDomain}/assets/img/logos/okta-logo.47066819ac7db5c13f4c431b2687cef6.png",
  "favicon": "https://{yourOktaDomain}/favicon.ico",
  "backgroundImage": null,
  "primaryColorHex": "#1662dd",
  "primaryColorContrastHex": "#000000",
  "secondaryColorHex": "#ebebed",
  "secondaryColorContrastHex": "#000000",
  "signInPageTouchPointVariant": "OKTA_DEFAULT",
  "endUserDashboardTouchPointVariant": "OKTA_DEFAULT",
  "errorPageTouchPointVariant": "OKTA_DEFAULT",
  "emailTemplateTouchPointVariant": "OKTA_DEFAULT",
  "loadingPageTouchPointVariant": "OKTA_DEFAULT",
  "_links": {
    "favicon": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/favicon",
      "hints": {
        "allow": [
          "POST",
          "DELETE"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    },
    "logo": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/logo",
      "hints": {
        "allow": [
          "POST",
          "DELETE"
        ]
      }
    },
    "background-image": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/background-image",
      "hints": {
        "allow": [
          "POST",
          "DELETE"
        ]
      }
    }
  }
}

The following example shows validation errors.

Request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "primaryColorHex": "#16",
    "secondaryColorHex": "#eb",
    "signInPageTouchPointVariant": "OKTA_DEFAULT_RANDOM",
    "endUserDashboardTouchPointVariant": "OKTA_DEFAULT_RANDOM",
    "errorPageTouchPointVariant": "OKTA_DEFAULT_RANDOM",
    "emailTemplateTouchPointVariant": "OKTA_DEFAULT_RANDOM",
    "loadingPageTouchPointVariant": "OKTA_DEFAULT_RANDOM"
}' "https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}"

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "errorCode": "E0000001",
    "errorSummary": "Api validation failed: primaryColorHex",
    "errorLink": "E0000001",
    "errorId": "oaezPopg5T7SbSuITpM1yz7Vg",
    "errorCauses": [
        {
            "errorSummary": "primaryColorHex: Invalid color hex: #16."
        },
        {
            "errorSummary": "secondaryColorHex: Invalid color hex: #eb."
        },
        {
            "errorSummary": "signInPageTouchPointVariant: 'OKTA_DEFAULT_RANDOM' is invalid. Valid values: [OKTA_DEFAULT, BACKGROUND_SECONDARY_COLOR, BACKGROUND_IMAGE]."
        },
        {
            "errorSummary": "errorPageTouchPointVariant: 'OKTA_DEFAULT_RANDOM' is invalid. Valid values: [OKTA_DEFAULT, BACKGROUND_SECONDARY_COLOR, BACKGROUND_IMAGE]."
        },
        {
            "errorSummary": "emailTemplateTouchPointVariant: 'OKTA_DEFAULT_RANDOM' is invalid. Valid values: [OKTA_DEFAULT, FULL_THEME]."
        },
        {
            "errorSummary": "endUserDashboardTouchPointVariant: 'OKTA_DEFAULT_RANDOM' is invalid. Valid values: [OKTA_DEFAULT, WHITE_LOGO_BACKGROUND, FULL_THEME, LOGO_ON_FULL_WHITE_BACKGROUND]."
        },
        {
            "errorSummary": "loadingPageTouchPointVariant: 'OKTA_DEFAULT_RANDOM' is invalid. Valid values: [OKTA_DEFAULT, NONE]."
        }
    ]
}

Upload Theme Logo

POST /api/v1/brands/${brandId}/themes/${themeId}/logo

Updates the logo for your Theme

Request path parameters

Parameter	Type	Description
brandId	String (URL)	ID of a Brand
themeId	String (URL)	ID of a Theme

Request body

Property	Type	Description
file	File	The file must be in PNG, JPG, or GIF format and less than 1 MB. For best results use landscape orientation, a transparent background, and a minimum size of 420 px by 120 px to prevent upscaling.

Response body

Returns 201 Created with logo URL

Passing an invalid brandId or an invalid themeId returns a 404 Not Found status code with the error code E0000007.

Passing an invalid file returns a 400 Bad Request status code with the error code E0000001.

Use examples

The following request updates the Theme logo with the uploaded file.

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
-F 'file=@/path/to/file' \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}/logo"

Response

HTTP/1.1 201 Content Created
Content-Type: application/json

{
  "url": "https://{yourOktaDomain}/bc/image/fileStoreRecord?id=fs09yfpj6PnWzgzIQ0g4"
}

The following request shows invalid logo validations.

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
-F 'file=@/path/to/invalid-file' \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}/logo"

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: file",
  "errorLink": "E0000001",
  "errorId": "oaeuDAe4dpETauG5euWTEqxLQ",
  "errorCauses": [
    {
      "errorSummary": "Your selected image is 4,158kB, which exceeds the 1,024kB limit"
    },
    {
      "errorSummary": "Your selected image is 5,568 pixels wide, which exceeds the 3,840 pixel limit"
    },
    {
      "errorSummary": "Your selected image is 11,136 pixels high, which exceeds the 2,160 pixel limit"
    }
  ]
}

Note: If you've enabled the theme builder feature, the /api/v1/org/logo endpoint still works, but pages use the logo from the theme.

See Logo scenarios for more information.

Delete Theme logo

DELETE /api/v1/brands/${brandId}/themes/${themeId}/logo

Deletes a Theme logo. The org then uses the Okta default logo.

Request path parameters

Parameter	Type	Description
brandId	String (URL)	ID of a Brand
themeId	String (URL)	ID of a Theme

Response body

None.

Passing an invalid brandId or an invalid themeId returns a 404 Not Found status code with the error code E0000007.

Use examples

The following request removes the uploaded Theme logo.

Request

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}/logo"

Response

HTTP/1.1 204 No Content

Upload Theme Favicon

POST /api/v1/brands/${brandId}/themes/${themeId}/favicon

Updates the favicon for your theme

Request body

Property	Type	Description
file	File	The file must be in PNG or ICO format and have a 1:1 ratio with a maximum dimension of 512 x 512.

Response body

Returns 201 Created with the favicon URL

Passing an invalid brandId or an invalid themeId returns a 404 Not Found status code with the error code E0000007.

Passing an invalid file returns a 400 Bad Request status code with the error code E0000001.

Use examples

The following request updates the Theme favicon with the uploaded file.

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
-F 'file=@/path/to/file' \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}/favicon"

Response

HTTP/1.1 201 Content Created
Content-Type: application/json

{
  "url": "https://{yourOktaDomain}/bc/image/fileStoreRecord?id=fs09yfpj6PnWzgzIQ0g4"
}

The following request shows validations for invalid favicon dimensions.

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
-F 'file=@/path/to/invalid-file' \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}/favicon"

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: file",
  "errorLink": "E0000001",
  "errorId": "oae-71S2vP_TWWqdCVEndqHCw",
  "errorCauses": [
    {
      "errorSummary": "Your selected image should be in a 1:1 ratio for width and height. Found 199 x 200. The image should be 199 x 199 or 200 x 200."
    }
  ]
}

Delete Theme favicon

DELETE /api/v1/brands/${brandId}/themes/${themeId}/favicon

Deletes a Theme favicon. The org then uses the Okta default favicon.

Request path parameters

Parameter	Type	Description
brandId	String (URL)	ID of a Brand
themeId	String (URL)	ID of a Theme

Response body

None.

Passing an invalid brandId or an invalid themeId returns a 404 Not Found status code with the error code E0000007.

Use examples

The following request removes the uploaded Theme favicon.

Request

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}/favicon"

Response

HTTP/1.1 204 No Content

Upload Theme background image

POST /api/v1/brands/${brandId}/themes/${themeId}/background-image

Updates the background image for your Theme

Request body

Property	Type	Description
file	File	The image must be a PNG, JPG, or GIF file and be less than 2 MB.

Response body

Returns 201 Created with the background image URL

Passing an invalid brandId or an invalid themeId returns a 404 Not Found status code with the error code E0000007.

Passing an invalid file returns a 400 Bad Request status code with the error code E0000001.

Use examples

The following request updates the Theme background image with the uploaded file.

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
-F 'file=@/path/to/file' \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}/background-image"

Response

HTTP/1.1 201 Content Created
Content-Type: application/json

{
  "url": "https://{yourOktaDomain}/bc/image/fileStoreRecord?id=fs09yfpj6PnWzgzIQ0g4"
}

The following request shows background image validations.

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Authorization: SSWS ${api_token}" \
-F 'file=@/path/to/invalid-file' \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}/background-image"

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: file",
  "errorLink": "E0000001",
  "errorId": "oae_eZ88QUzReSZcxI_e1H9Aw",
  "errorCauses": [
    {
      "errorSummary": "Your selected image is 11,136 pixels high, which exceeds the 8,000 pixel limit."
    }
  ]
}

Delete Theme background image

DELETE /api/v1/brands/${brandId}/themes/${themeId}/background-image

Deletes a Theme background image

Request path parameters

Parameter	Type	Description
brandId	String (URL)	ID of a Brand
themeId	String (URL)	ID of a Theme

Response body

None.

Passing an invalid brandId or an invalid themeId returns a 404 Not Found status code with the error code E0000007.

Use examples

The following request removes the uploaded Theme background image.

Request

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/themes/${themeId}/background-image"

Response

HTTP/1.1 204 No Content

Email template operations

The Email Templates API allows you to programmatically manage email customizations.

Email Templates

Okta provides many customizable email templates. For example, the UserActivation email template allows users to activate their account. Each template has default content that Okta translates to any one of the supported languages.

Email Customizations

Email customizations allow you to override an email template's default content.

The following constraints apply to email customizations:

• If an email template has any customizations at all, exactly one of them must be the default (where isDefault is true). Okta uses the default customization when no other customization applies to the user's language settings.
• Each email template can have only one customization for each supported language.

Supported Languages

Email customizations can be created for the following languages. Language values must be in BCP 47 language tag (opens new window) format.

Language	BCP 47 language tag
Czech	cs
Danish	da
German	de
Greek	el
English	en
Spanish	es
Finnish	fi
French	fr
Hungarian	hu
Indonesian	id
Italian	it
Japanese	ja
Korean	ko
Malaysian	ms
Norwegian	nb
Dutch	nl-NL
Polish	pl
Portuguese	pt-BR
Romanian	ro
Russian	ru
Swedish	sv
Thai	th
Turkish	tr
Ukrainian	uk
Vietnamese	vi
Chinese (simplified)	zh-CN
Chinese (traditional)	zh-TW

• List email templates
• Get email template
• Get email template default content
• Preview email template default content
• Send test email
• List email customizations
• Create email customization
• Delete all email customizations
• Get email customization
• Update email customization
• Delete email customization
• Preview email customization

List email templates

GET /api/v1/brands/${brandId}/templates/email

Lists all supported email templates

Request path parameters

Parameter	Description	ParamType	DataType	Required
brandId	ID of a Brand string	Query	String	TRUE
expand	If specified, it causes more metadata to be included in the response. Supported values: settings and/or customizationCount. Use commas to separate values if both are used.	Query	String	FALSE

Response body

A paginated list of Email Template resources

Passing an invalid brandId returns a 404 Not Found with the error code E0000007.

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email"

Response

HTTP/1.1 200 OK
Link: <http://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email?limit=10>; rel="self",
  <http://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email?after=ADUserActivation&limit=10>; rel="next"

[
    {
        "name": "UserActivation",
        "_links": {
            "customizations": {
                "hints": {
                    "allow": [
                        "GET",
                        "POST",
                        "DELETE"
                    ]
                },
                "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations"
            },
            "defaultContent": {
                "hints": {
                    "allow": [
                        "GET"
                    ]
                },
                "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/default-content"
            },
            "self": {
                "hints": {
                    "allow": [
                        "GET"
                    ]
                },
                "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation"
            },
            "test": {
                "hints": {
                    "allow": [
                        "POST"
                    ]
                },
                "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/test"
            }
        }
    },
    ...
    {
        "name": "ADUserActivation",
        "_links": {
          ...
        }
    }
]

Get email template

GET /api/v1/brands/${brandId}/templates/email/${templateName}

Fetches the email template named templateName

Request path parameters

Parameter	Description	ParamType	DataType	Required
brandId	ID of a Brand string	Query	String	TRUE
templateName	Name of an email template	Query	String	TRUE
expand	If specified, it causes more metadata to be included in the response. Supported values: settings and/or customizationCount. Use commas to separate values if both are used.	Query	String	FALSE

Response body

The requested Email Template resource.

Passing an invalid brandId or templateName returns a 404 Not Found with the error code E0000007.

Use examples

The following example returns the UserActivation email template.

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation?expand=settings,customizationCount"

Response

HTTP/1.1 200 OK

{
    "name": "UserActivation",
    "_embedded": {
      "settings": {
        "recipients": "ALL_USERS",
        "_links": { ... }
      },
      "customizationCount": 3
    },
    "_links": {
        "customizations": {
            "hints": {
                "allow": [
                    "GET",
                    "POST",
                    "DELETE"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations"
        },
        "defaultContent": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/default-content"
        },
        "self": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation"
        },
        "test": {
            "hints": {
                "allow": [
                    "POST"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/test"
        }
    }
}

Get email template default content

GET /api/v1/brands/${brandId}/templates/email/${templateName}/default-content

Fetches an email template's default content

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template

Request query parameters

Parameter	Type	Description
language	String	One of the supported BCP 47 language codes

Response body

The requested email template's default Email Content resource.

Passing an invalid brandId or templateName returns a 404 Not Found with the error code E0000007.

If language isn't specified or is invalid, it defaults to the current user's language.

Use examples

The following example returns the UserActivation email template's default content.

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/default-content"

Response

HTTP/1.1 200 OK

{
    "body": "<!DOCTYPE html><html>...</html>",
    "subject": "Welcome to Okta!",
    "_links": {
        "preview": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/default-content/preview"
        },
        "self": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/default-content"
        },
        "template": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation"
        }
    }
}

Preview email template default content

GET /api/v1/brands/${brandId}/templates/email/${templateName}/default-content/preview

Fetches a preview of an email template's default content

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template

Request query parameters

Parameter	Type	Description
language	String	One of the supported BCP 47 language codes

Response body

The requested email template's default Email Content resource, with variables populated using the current user's context.

Passing an invalid brandId or templateName returns a 404 Not Found with the error code E0000007.

If language isn't specified or is invalid, it defaults to the current user's language.

Use examples

The following example returns a preview of the UserActivation email template's default content.

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/default-content/preview"

Response

HTTP/1.1 200 OK

{
    "body": "<!DOCTYPE html><html>...</html>",
    "subject": "Welcome to Okta!",
    "_links": {
        "defaultContent": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/default-content"
        },
        "self": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/default-content/preview"
        },
        "template": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation"
        }
    }
}

Send test email

POST /api/v1/brands/${brandId}/templates/email/${templateName}/test

Sends a test email

The following set of priorities determines the content of the email:

1. The email customization for the language specified in the language query parameter.
2. The email template's default customization.
3. The email template’s default content, translated to the current user's language.

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template

Request query parameters

Parameter	Type	Description
language	String	One of the supported BCP 47 language codes

Response body

Returns a 204 No Content on success.

Passing an invalid brandId or templateName returns a 404 Not Found with the error code E0000007.

If language isn't specified or is invalid, it defaults to the current user's language.

Use examples

The following example sends a test UserActivation email in French (fr).

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/test?language=fr"

Response

HTTP/1.1 204 No Content

List email customizations

GET /api/v1/brands/${brandId}/templates/email/${templateName}/customizations

Lists all customizations for an email template

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template

Response body

A paginated list of Email Customization resources

Passing an invalid brandId or templateName returns a 404 Not Found with the error code E0000007.

Use examples

The following example returns the list of all customizations for the UserActivation email template.

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations"

Response

HTTP/1.1 200 OK
Link: <https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations?limit=10>; rel="self",
  <https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations?after=oel2hr0orNF3xGHpS0g4&limit=10>; rel="next"

[
    {
        "body": "<!DOCTYPE html><html>...</html>",
        "created": "2022-01-24T23:22:36.000Z",
        "id": "oel2hr0orNF3xGHpS0g4",
        "isDefault": true,
        "language": "en",
        "lastUpdated": "2022-01-25T03:22:52.000Z",
        "subject": "Welcome to Okta!"
        "_links": {
            "preview": {
                "hints": {
                    "allow": [
                        "GET"
                    ]
                },
                "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/oel2hr0orNF3xGHpS0g4/preview"
            },
            "self": {
                "hints": {
                    "allow": [
                        "GET",
                        "PUT",
                        "DELETE"
                    ]
                },
                "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/oel2hr0orNF3xGHpS0g4"
            },
            "template": {
                "hints": {
                    "allow": [
                        "GET"
                    ]
                },
                "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation"
            },
            "test": {
                "hints": {
                    "allow": [
                        "POST"
                    ]
                },
                "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/test"
            }
        },
    },
    ...
]

Create email customization

POST /api/v1/brands/${brandId}/templates/email/${templateName}/customizations

Creates an email customization

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template

Request body

The Email Customization resource to create.

Response body

The Email Customization resource that was created.

If this is the first customization being created for the email template, isDefault is set to true.

Returns a 400 Bad Request if:

• The language parameter isn’t one of the supported languages.
• The body parameter doesn’t contain a required variable reference.

Returns a 409 Conflict with the error code E0000182 if isDefault is true and a default customization exists.

Passing an invalid brandId or templateName returns a 404 Not Found with the error code E0000007.

Note: See Email Customizations for details about email customization constraints.

Use examples

The following example creates an English customization for the UserActivation email template.

Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "language": "en",
  "subject": "Welcome to Okta!",
  "body": "<!DOCTYPE html><html>...${activationLink}...</html>",
  "isDefault": true
}' \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations"

Response

HTTP/1.1 201 Created

{
    "body": "<!DOCTYPE html><html>...${activationLink}...</html>",
    "created": "2022-01-27T05:42:07.000Z",
    "id": "oel2kk2VDW0K4AOZp0g4",
    "isDefault": false,
    "language": "en",
    "lastUpdated": "2022-01-27T05:42:07.000Z",
    "subject": "Welcome to Okta!",
    "_links": {
        "preview": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/oel2kk2VDW0K4AOZp0g4/preview"
        },
        "self": {
            "hints": {
                "allow": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/oel2kk2VDW0K4AOZp0g4"
        },
        "template": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation"
        },
        "test": {
            "hints": {
                "allow": [
                    "POST"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/test"
        }
    }
}

Delete all email customizations

DELETE /api/v1/brands/${brandId}/templates/email/${templateName}/customizations

Deletes an email customization

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template

Response body

Returns a 204 No Content on success.

Passing an invalid brandId or templateName returns a 404 Not Found with the error code E0000007.

Use examples

The following example deletes all customizations of the UserActivation email template.

Request

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations"

Response

HTTP/1.1 204 No Content

Get email customization

GET /api/v1/brands/${brandId}/templates/email/${templateName}/customizations/${customizationId}

Fetches an email customization

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template
customizationId	String	ID of an Email Customization

Response body

The requested Email Customization resource.

Passing an invalid brandId, templateName, or customizationId returns a 404 Not Found with the error code E0000007.

Use examples

The following example returns a specific customization of the UserActivation email template.

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/${customizationId}"

Response

HTTP/1.1 200 OK

{
    "body": "<!DOCTYPE html><html>...</html>",
    "created": "2022-01-27T05:42:07.000Z",
    "id": "oel2kk2VDW0K4AOZp0g4",
    "isDefault": true,
    "language": "en",
    "lastUpdated": "2022-01-27T05:42:07.000Z",
    "subject": "Welcome to Okta!",
    "_links": {
        "preview": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/oel2kk2VDW0K4AOZp0g4/preview"
        },
        "self": {
            "hints": {
                "allow": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/oel2kk2VDW0K4AOZp0g4"
        },
        "template": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation"
        },
        "test": {
            "hints": {
                "allow": [
                    "POST"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/test"
        }
    }
}

Update email customization

PUT /api/v1/brands/${brandId}/templates/email/${templateName}/customizations/${customizationId}

Updates an email customization

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template
customizationId	String	ID of an Email Customization

Request body

The Email Customization resource to update.

Response body

The Email Customization resource that was updated.

If the isDefault parameter is true, the previous default email customization has isDefault set to false.

Returns a 409 Conflict if:

• There’s already another email customization for the specified language.
• The isDefault parameter is false and the email customization being updated is the default.

Returns a 400 Bad Request if:

• The language parameter isn’t one of the supported locales.
• The body parameter doesn’t contain a required variable reference.

Passing an invalid brandId, templateName, or customizationId returns a 404 Not Found with the error code E0000007.

Note: See Email Customizations for details about email customization constraints.

Use examples

The following example updates a customization for the UserActivation email template.

Request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "language": "en",
  "subject": "Hello from Okta!",
  "body": "<!DOCTYPE html><html>...${activationLink}...</html>",
  "isDefault": true
}' \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/${customizationId}"

Response

HTTP/1.1 200 OK

{
    "body": "<!DOCTYPE html><html>...${activationLink}...</html>",
    "created": "2022-01-27T00:23:48.000Z",
    "id": "oel2kk1zYJBJbeaGo0g4",
    "isDefault": true,
    "language": "en",
    "lastUpdated": "2022-01-27T00:23:48.000Z",
    "subject": "Hello from Okta!",
    "_links": {
        "preview": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/oel2kk1zYJBJbeaGo0g4/preview"
        },
        "self": {
            "hints": {
                "allow": [
                    "GET",
                    "PUT",
                    "DELETE"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/oel2kk1zYJBJbeaGo0g4"
        },
        "template": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation"
        },
        "test": {
            "hints": {
                "allow": [
                    "POST"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/test"
        }
    }
}

Delete email customization

DELETE /api/v1/brands/${brandId}/templates/email/${templateName}/customizations/${customizationId}

Deletes an email customization

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template
customizationId	String	ID of an Email Customization

Response body

Returns a 204 No Content on success.

Returns a 409 Conflict if the email customization to be deleted is the default.

Passing an invalid brandId, templateName, or customizationId returns a 404 Not Found with the error code E0000007.

Note: See Email Customizations for details about email customization constraints.

Use examples

The following example deletes a specific customization of the UserActivation email template.

Request

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/${customizationId}"

Response

HTTP/1.1 204 No Content

Preview email customization

GET /api/v1/brands/${brandId}/templates/email/${templateName}/customizations/${customizationId}/preview

Fetches a preview of an email customization

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template
customizationId	String	ID of an Email Customization

Response body

The requested email customization's Email Content resource, with variables populated using the current user's context.

Passing an invalid brandId, templateName, or customizationId returns a 404 Not Found with the error code E0000007.

Use examples

The following example returns a preview of a customization of the UserActivation email template.

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/${customizationId}/preview"

Response

HTTP/1.1 200 OK

{
    "body": "<!DOCTYPE html><html>...</html>",
    "subject": "Welcome to Okta!",
    "_links": {
        "self": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/customizations/oel2kk1zYJBJbeaGo0g4/preview"
        },
        "template": {
            "hints": {
                "allow": [
                    "GET"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation"
        },
        "test": {
            "hints": {
                "allow": [
                    "POST"
                ]
            },
            "href": "https://{yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/test"
        }
    }
}

Email Template Settings

This API lets you manage the settings of each customizable email template.

Get Email Template Settings

GET /api/v1/brands/${brandId}/templates/email/${templateName}/settings

Fetches the settings associated with the template

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template

Response body

The requested Email Template Settings resource, with variables populated using the current user's context

Passing an invalid brandId or templateName returns a 404 Not Found with the error code E0000007.

Use examples

The following example returns the settings for the email template UserActivation.

Request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/settings"

Response

HTTP/1.1 200 OK

{
    "recipients": "ALL_USERS",
    "_links": {
      "template": {
            "href": "https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        },
        "self": {
            "href": "https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/settings",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        }
    }
}

Update Email Template Settings

PUT /api/v1/brands/${brandId}/templates/email/${templateName}/settings

Updates the settings associated with the template

Request path parameters

Parameter	Type	Description
brandId	String	ID of a Brand
templateName	String	Name of an Email Template

Request body

The Email Template Settings Object resource to update

Response body

The Email Template Settings Object resource that was updated

Passing an invalid brandId or templateName returns a 404 Not Found with the error code E0000007.

Use examples

The following example disables the UserActivation email from being sent.

Request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "recipients": "NO_USERS"
}' \
"https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/settings"

Response

HTTP/1.1 200 OK

{
    "recipients": "NO_USERS",
    "_links": {
        "template": {
            "href": "https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation",
            "hints": {
                "allow": [
                    "GET"
                ]
            }
        },
        "self": {
            "href": "https://${yourOktaDomain}/api/v1/brands/${brandId}/templates/email/UserActivation/settings",
            "hints": {
                "allow": [
                    "GET",
                    "PUT"
                ]
            }
        }
    }
}

Sign-in page operations

See the Customized sign-in page API reference (opens new window) on the new beta reference site.

Sign-out page operations

See the Customized Sign-out Page API reference (opens new window) on the new beta reference site.

Error page operations

See the Customized Error Page API reference (opens new window) on the new beta reference site.

Brand API Objects

Brand object

The Brand request object defines the following properties:

Property	Type	Description
agreeToCustomPrivacyPolicy	boolean	(Optional) Consent for updating the custom privacy policy URL. Not required when resetting the URL.
customPrivacyPolicyUrl	String	Custom privacy policy URL. Default value: null.
removePoweredByOkta	boolean	(Optional) Removes "Powered by Okta" from the Okta-hosted sign-in page, and "© 2021 Okta, Inc." from the Okta End-User Dashboard. Default value: false.
_links	Links	Link relations for this object

Brand example

Updates a custom privacy policy URL for a brand

{
  "agreeToCustomPrivacyPolicy": true,
  "customPrivacyPolicyUrl": "https://www.someHost.com/privacy-policy"
}

Resets a privacy policy URL

{
  "customPrivacyPolicyUrl": null
}

Updates the setting to remove the "Powered by Okta" wording

{
  "agreeToCustomPrivacyPolicy": true,
  "removePoweredByOkta": true,
  "customPrivacyPolicyUrl": "https://www.someHost.com/privacy-policy"
}

Brand Response object

The Brand Response object defines the following properties:

Property	Type	Description
customPrivacyPolicyUrl	String	Custom privacy policy URL
removePoweredByOkta	boolean	Removes "Powered by Okta" from the Okta-hosted sign-in page and "© 2021 Okta, Inc." from the Okta End-User Dashboard.
id	String	Brand ID
_links	Links	Link relations for this object

Brand response example

{
  "id": "bndul904tTZ6kWVhP0g3",
  "customPrivacyPolicyUrl": null,
  "removePoweredByOkta": false,
  "_links": {
    "themes": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes",
      "hints": {
        "allow": [
          "GET"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    }
  }
}

Theme API objects

Theme object

The Theme object defines the following properties:

Property	Type	Description	Default Value
primaryColorHex	String	Primary color hex code	#1662dd
primaryColorContrastHex	String	(Optional) Primary color contrast hex code. Accepted values: #000000, #ffffff.	#ffffff
secondaryColorHex	String	Secondary color hex code	#ebebed
secondaryColorContrastHex	String	(Optional) Secondary color contrast hex code. Accepted values: #000000, #ffffff.	#000000
signInPageTouchPointVariant	Enum	Variant for sign-in page. Accepted values: OKTA_DEFAULT, BACKGROUND_SECONDARY_COLOR, BACKGROUND_IMAGE.	OKTA_DEFAULT
endUserDashboardTouchPointVariant	Enum	Variant for the Okta End-User Dashboard. Accepted values: OKTA_DEFAULT, WHITE_LOGO_BACKGROUND, FULL_THEME, LOGO_ON_FULL_WHITE_BACKGROUND.	OKTA_DEFAULT
errorPageTouchPointVariant	Enum	Variant for the error page. Accepted values: OKTA_DEFAULT, BACKGROUND_SECONDARY_COLOR, BACKGROUND_IMAGE.	OKTA_DEFAULT
emailTemplateTouchPointVariant	Enum	Variant for email templates. Accepted values: OKTA_DEFAULT, FULL_THEME.	OKTA_DEFAULT
loadingPageTouchPointVariant	Enum	(Optional) Variant for the Okta loading page. Applicable only if the Loading Page Animation feature is enabled. Accepted values: OKTA_DEFAULT, NONE.	OKTA_DEFAULT

Note: Okta optimizes the primaryColorContrastHex and secondaryColorContrastHex properties for the highest contrast between the font color and the background or button color. To disable or override the contrast auto-detection, update either contrast value with an accepted contrast hex code. Any update disables future automatic optimizations for the contrast hex.

Note: Contrast color is used by pages to optimize the opacity of text color when primary or secondary color is used as the background.

Note: For existing orgs with customizations, refer to the following table for different scenarios with initial variant values.

Variant Definition

You can publish a theme for a page or email template with different combinations of assets, and variants are preset combinations of those assets.

Variants for the Okta sign-in page

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

Enum Value	Description
OKTA_DEFAULT	Use the Okta logo and Okta favicon with no background image, and the Okta colors on the Okta sign-in page.
BACKGROUND_SECONDARY_COLOR	Use the logo and favicon from the Theme with the secondaryColorHex as the background color for the Okta sign-in page.
BACKGROUND_IMAGE	Use the logo, favicon, and background image from the Theme.

Variants for the Okta End-User Dashboard:

Enum Value	Description
OKTA_DEFAULT	Use the Okta logo and Okta favicon with a white background color for the logo and the side navigation bar background color.
WHITE_LOGO_BACKGROUND	Use the logo from the Theme with a white background color for the logo, use the favicon from the Theme, and use primaryColorHex for the side navigation bar background color.
FULL_THEME	Use the logo from the Theme, primaryColorHex for the logo and the side navigation bar background color, and use the favicon from the Theme.
LOGO_ON_FULL_WHITE_BACKGROUND	Use the logo from the Theme, white background color for the logo and the side navigation bar background color, and use the favicon from the Theme.

Variants for Error Page:

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

Enum Value	Description
OKTA_DEFAULT	Use the Okta logo, the Okta favicon, and the Okta background. color.
BACKGROUND_SECONDARY_COLOR	Use the logo from the Theme with secondaryColorHex as the background color for the error page and use the favicon from the Theme.
BACKGROUND_IMAGE	Use the logo, the favicon, and the background image from the Theme.

Variants for Email Templates:

Enum Value	Description
OKTA_DEFAULT	Use the Okta logo and the Okta colors in the email templates.
FULL_THEME	Use the logo from the Theme and primaryColorHex as the background color for buttons.

Variants for the Okta loading page

Enum Value	Description
OKTA_DEFAULT	Use the default Okta loading page animation during the redirect.
NONE	Use no loading page animation during the redirect.

Theme example

{
  "primaryColorHex": "#1662dd",
  "primaryColorContrastHex": "#ffffff",
  "secondaryColorHex": "#ebebed",
  "secondaryColorContrastHex": "#ffffff",
  "signInPageTouchPointVariant": "OKTA_DEFAULT",
  "endUserDashboardTouchPointVariant": "OKTA_DEFAULT",
  "errorPageTouchPointVariant": "OKTA_DEFAULT",
  "emailTemplateTouchPointVariant": "OKTA_DEFAULT",
  "loadingPageTouchPointVariant": "OKTA_DEFAULT"
}

Theme Response object

Theme Response properties

The Theme Response object defines the following properties:

Property	Type	Description
id	String	Theme ID
logo	String	Logo URL
favicon	String	Favicon URL
backgroundImage	String	Background image URL
primaryColorHex	String	Primary color hex code
primaryColorContrastHex	String	Primary color contrast hex code
secondaryColorHex	String	Secondary color hex code
secondaryColorContrastHex	String	Secondary color contrast hex code
signInPageTouchPointVariant	Enum	Variant for the Okta sign-in page
endUserDashboardTouchPointVariant	Enum	Variant for the Okta End-User Dashboard
errorPageTouchPointVariant	Enum	Variant for the error page
emailTemplateTouchPointVariant	Enum	Variant for email templates
loadingPageTouchPointVariant	Enum	Variant for the Okta loading page
_links	Links	Link relations for this object

Theme Response example

{
  "id": "thdul904tTZ6kWVhP0g3",
  "logo": "https://{yourOktaDomain}/assets/img/logos/okta-logo.47066819ac7db5c13f4c431b2687cef6.png",
  "favicon": "https://{yourOktaDomain}/favicon.ico",
  "backgroundImage": null,
  "primaryColorHex": "#1662dd",
  "primaryColorContrastHex": "#000000",
  "secondaryColorHex": "#ebebed",
  "secondaryColorContrastHex": "#000000",
  "signInPageTouchPointVariant": "OKTA_DEFAULT",
  "endUserDashboardTouchPointVariant": "OKTA_DEFAULT",
  "errorPageTouchPointVariant": "OKTA_DEFAULT",
  "emailTemplateTouchPointVariant": "OKTA_DEFAULT",
  "loadingPageTouchPointVariant": "OKTA_DEFAULT",
  "_links": {
    "favicon": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/favicon",
      "hints": {
        "allow": [
          "POST",
          "DELETE"
        ]
      }
    },
    "self": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3",
      "hints": {
        "allow": [
          "GET",
          "PUT"
        ]
      }
    },
    "logo": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/logo",
      "hints": {
        "allow": [
          "POST",
          "DELETE"
        ]
      }
    },
    "background-image": {
      "href": "https://{yourOktaDomain}/api/v1/brands/bndul904tTZ6kWVhP0g3/themes/thdul904tTZ6kWVhP0g3/background-image",
      "hints": {
        "allow": [
          "POST",
          "DELETE"
        ]
      }
    }
  }
}

Image Upload Response object

The Image Upload Response object defines the following properties:

Property	Type	Description
url	String	URL of uploaded image

Image Upload Response example

{
  "url": "https://{yourOktaDomain}/assets/img/logos/okta-logo.47066819ac7db5c13f4c431b2687cef6.png"
}

Existing org scenarios

Data migration from existing orgs

Initial Theme variant values are different for existing orgs with customizations.

Property	Org Logo Uploaded	Background Image Uploaded	Initial Value
signInPageTouchPointVariant	no	no	OKTA_DEFAULT
signInPageTouchPointVariant	yes	no	BACKGROUND_SECONDARY_COLOR
signInPageTouchPointVariant	yes	yes	BACKGROUND_IMAGE
errorPageTouchPointVariant	no	no	OKTA_DEFAULT
errorPageTouchPointVariant	yes	no	BACKGROUND_SECONDARY_COLOR
errorPageTouchPointVariant	yes	yes	BACKGROUND_IMAGE
endUserDashboardTouchPointVariant	no	n/a	OKTA_DEFAULT
endUserDashboardTouchPointVariant	yes	n/a	LOGO_ON_FULL_WHITE_BACKGROUND
loadingPageTouchPointVariant	n/a	n/a	OKTA_DEFAULT or NONE

Logo scenarios

The following scenarios explain which logo is used when based on the THEME_BUILDER flag.

THEME_BUILDER feature status	Can Upload Org Logo	Can Upload Theme Logo	Logo Used On Pages
Enabled	yes	yes	Theme logo
Disabled	yes	no	Org logo

Notes: Enabling the THEME_BUILDER feature automatically updates the Theme logo from Org. The Org logo is still stored. Disabling the THEME_BUILDER feature uses the logo configured for the Org. Pages use the logo from the preceding source based on feature status.

Email Template Resources

Email Template

The Email Template resource defines the following properties:

Property	Type	Description
name	String	The name of the email template
_links	Links	Link relations for this object

Email Content

The Email Content resource defines the following properties:

Property	Type	Description
subject	String	The subject of the email
body	String	The body of the email
_links	Links	Link relations for this object

Email Customization

The Email Customization resource defines the following properties:

Property	Type	Description
id	String	The ID of the customization
language	String	The language supported by the customization
isDefault	boolean	Whether the customization is the default
subject	String	The subject of the customization
body	String	The body of the customization
_links	Links	Link relations for this object

Email Template Settings Object

The Email Template Settings Object resource defines the following properties:

Property	Type	Description
_links	Links	Link relations for this object

Recipients Enum

Enum Value	Description
ALL_USERS	Send emails to all users (default)
ADMINS_ONLY	Send emails to administrators only
NO_USERS	Don’t send emails to any user

Links object

Specifies link relations available for the status of an application using the JSON Hypertext Application Language (opens new window) specification. This object is used for dynamic discovery of related resources and lifecycle operations. The Links object is read-only. See Web Linking (opens new window)) for more information on link relations.