Migrate your brand customizations with automation

This guide details how to automate copying custom brand settings from an Okta test environment to a live production environment. This migration includes CSS, email content, and error page HTML for Terraform, Powershell CLI, and the Okta APIs. Switch between these three tools using the dropdown list on the right.

---

Learning outcomes

Configure and run a brand customization synchronization from a test or preview environment to a production environment using automated tools.

What you need

• A branded Okta test or preview org and a production Okta org

• Automated tooling (Terraform provider, PowerShell module, or Okta CLI client)

• Okta Terraform provider 4.9.1 or later (for Terraform users)

• PowerShell 7.0+ and Okta.PowerShell module v2.0.2+ (for PowerShell users)

• Go-based okta-cli-client (for CLI users - currently in Beta, requires source compilation)

---

Prerequisites

This guide assumes that you have already registered and verified separate custom domains for your test and production environments (for example, test.example.com and portal.example.com). Okta also assumes that your Terraform or CLI tools are fully authenticated and configured.

Important: You can create brands programmatically, but themes are automatically generated when a brand is created. Import existing themes before you manage them with automation tools. This guide demonstrates the proper import workflow.

New to these tools? If you haven’t configured authentication or installed the necessary SDKs (Terraform provider, PowerShell module, Okta Go CLI), refer to the introductory guides on the respective GitHub repositories before proceeding.

Limitations

• The Okta Management API doesn't provide endpoints to customize the generic, system-generated SMS messages (such as those used for MFA codes). This functionality remains limited to the Admin Console interface.
• You can't create or delete themes programmatically, each brand automatically receives exactly one theme that can only be read and updated.
• You can't modify custom error page HTML content when multibrand customization is enabled in your org.

Tool setup

Setting up secure automation starts with choosing the right authentication method, whether you're using Terraform for infrastructure, PowerShell for scripting, or making direct API calls. This section provides the steps to configure OAuth 2.0 service apps and mobile integrations to ensure that your tools have the precise permissions they need without compromising security. By the end of this section, you'll know how to manage environment-specific variables and establish a secure connection to your Okta org.

You can obtain the OAuth 2.0 access token using the client credentials flow with your service app credentials. Set environment variables to switch between test and production environments.

  # Set variables for test environment
  export OKTA_ORG_URL="https://dev-test.com"
  export OKTA_CLIENT_ID="0oa1234567890abcdef"
  export OKTA_PRIVATE_KEY_PATH="./keys/test-private-key.pem"

  # To target production, change these variables:
  # export OKTA_ORG_URL="https://acme-prod.okta.com"
  # export OKTA_CLIENT_ID="0oa9876543210fedcba"
  # export OKTA_PRIVATE_KEY_PATH="./keys/prod-private-key.pem"

To obtain an access token, you need to create a JWT and exchange it for an OAuth 2.0 access token. Terraform and PowerShell handle this process automatically. For direct API calls, you can use a helper script or library to generate the JWT.

Define reusable branding content

All customization logic is centralized into reusable blocks (content strings) that are applied identically across both environments.

Synchronize branding metadata

This step ensures that the core brand object exists and is correctly linked to the custom domain of the target environment (test or production).

# List existing brands
curl -X GET "${OKTA_ORG_URL}/api/v1/brands" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json"

# Most commonly, you work with your existing default brand (first in the list)
BRAND_ID=$(curl -s -X GET "${OKTA_ORG_URL}/api/v1/brands" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" | jq -r '.[0].id')

echo "Working with Brand ID: $BRAND_ID"

# Update the brand properties
curl -X PUT "${OKTA_ORG_URL}/api/v1/brands/${BRAND_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Acme Co. User Portal Brand",
    "agreeToCustomPrivacyPolicy": true,
    "customPrivacyPolicyUrl": "https://www.acme.com/privacy",
    "removePoweredByOkta": true,
    "locale": "en"
  }'

# To create a NEW custom brand (requires the multibrand feature):
# curl -X POST "${OKTA_ORG_URL}/api/v1/brands" \
#   -H "Authorization: Bearer ${ACCESS_TOKEN}" \
#   -H "Content-Type: application/json" \
#   -H "Accept: application/json" \
#   -d '{
#     "name": "Acme Co. User Portal Brand",
#     "agreeToCustomPrivacyPolicy": true,
#     "customPrivacyPolicyUrl": "https://www.acme.com/privacy",
#     "removePoweredByOkta": true,
#     "locale": "en"
#   }'

Apply Sign-In Widget customization

Important: Themes are automatically created when a brand is created. Import existing themes before managing them.

# Get theme ID
THEME_ID=$(curl -s -X GET "${OKTA_ORG_URL}/api/v1/brands/${BRAND_ID}/themes" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" | jq -r '.[0].id')

echo "Updating Theme ID: $THEME_ID"

# Update theme colors and variants
curl -X PUT "${OKTA_ORG_URL}/api/v1/brands/${BRAND_ID}/themes/${THEME_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "primaryColorHex": "#0047AB",
    "secondaryColorHex": "#f0f4f8",
    "primaryColorContrastHex": "#FFFFFF",
    "secondaryColorContrastHex": "#000000",
    "signInPageTouchPointVariant": "BACKGROUND_SECONDARY_COLOR",
    "endUserDashboardTouchPointVariant": "OKTA_DEFAULT",
    "errorPageTouchPointVariant": "OKTA_DEFAULT",
    "emailTemplateTouchPointVariant": "OKTA_DEFAULT"
  }'

echo "Theme updated successfully"

# Optional: Upload logo (multipart/form-data)
# curl -X POST "${OKTA_ORG_URL}/api/v1/brands/${BRAND_ID}/themes/${THEME_ID}/logo" \
#   -H "Authorization: Bearer ${ACCESS_TOKEN}" \
#   -F "file=@./assets/logo.png"

# Optional: Upload background image
# curl -X POST "${OKTA_ORG_URL}/api/v1/brands/${BRAND_ID}/themes/${THEME_ID}/background-image" \
#   -H "Authorization: Bearer ${ACCESS_TOKEN}" \
#   -F "file=@./assets/background.jpg"

Apply email template customization

Synchronizes the email content defined in the Define reusable branding content section for key templates.

# Create or update UserActivation email template customization
# Note: EMAIL_BODY should contain your HTML email template
EMAIL_BODY='<html><body style="font-family: Arial, sans-serif;"><p>Hello ${user.profile.firstName},</p><p>Your new account has been created at ${org.name}.</p><p>Click <a href="${activationLink}">Activate My Account</a> to get started.</p><p>Thank you!</p></body></html>'

# Create a new customization (if it doesn't exist)
curl -X POST "${OKTA_ORG_URL}/api/v1/brands/${BRAND_ID}/templates/email/UserActivation/customizations" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{
    \"language\": \"en\",
    \"isDefault\": true,
    \"subject\": \"Welcome to Acme Co - Activate Your Account\",
    \"body\": $(echo "$EMAIL_BODY" | jq -Rs .)
  }"

# Or update an existing customization
# First get the customization ID
# CUSTOMIZATION_ID=$(curl -s -X GET "${OKTA_ORG_URL}/api/v1/brands/${BRAND_ID}/templates/email/UserActivation/customizations" \
#   -H "Authorization: Bearer ${ACCESS_TOKEN}" \
#   -H "Accept: application/json" | jq -r '.[0].id')
#
# curl -X PUT "${OKTA_ORG_URL}/api/v1/brands/${BRAND_ID}/templates/email/UserActivation/customizations/${CUSTOMIZATION_ID}" \
#   -H "Authorization: Bearer ${ACCESS_TOKEN}" \
#   -H "Content-Type: application/json" \
#   -H "Accept: application/json" \
#   -d "{
#     \"language\": \"en\",
#     \"isDefault\": true,
#     \"subject\": \"Welcome to Acme Co - Activate Your Account\",
#     \"body\": $(echo "$EMAIL_BODY" | jq -Rs .)
#   }"

echo "Email template customization applied"

Apply error page customization

Important: You can't modify custom error page HTML if multibrand customization is enabled in your org. This section only applies to orgs without multibrand.

# Note: Error page HTML customization is only supported when multibrand isn't enabled.
# This API call may return 403 if multibrand customization is enabled in your org.

ERROR_PAGE_HTML='<div style="text-align: center; padding: 50px; font-family: sans-serif;"><h1 style="color: #0047AB;">Oops! Something Went Wrong.</h1><p style="font-size: 1.2em;">We encountered an unexpected error.</p><p>Please check the URL or try again later.</p><a href="/" style="display: inline-block; margin-top: 20px; padding: 10px 20px; background-color: #0047AB; color: white; text-decoration: none; border-radius: 5px;">Go Home</a></div>'

curl -X PUT "${OKTA_ORG_URL}/api/v1/brands/${BRAND_ID}/pages/sign-in/customized" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{
    \"pageContent\": $(echo "$ERROR_PAGE_HTML" | jq -Rs .)
  }"

# If you receive a 403 error, multibrand customization is enabled
# and error page HTML customization isn't available.
echo "Error page customization applied (if multibrand is not enabled)"

Final synchronization step

After the content is defined in the script or configuration file:

1. Run against the test environment: Execute your chosen tool (Terraform apply, PowerShell script, or cURL commands) using the test environment variables or context.
2. Verify: Manually test the customization on your test custom domain (https://test.example.com/login/default).
3. Run against production: Change your environment variables (or tool configuration) to target production and re-run the exact same script or configuration. The code is designed to be idempotent and creates the brand in production using the production domain ID.