Branding Customization#

Dify supports two separate branding customization surfaces: workspace-level logo replacement (gated by subscription/billing) and enterprise-level branding (application title, logos, favicon — gated by deployment edition). The two are independent of each other and use different resolution paths.

Feature Models#

FeatureModel (per-workspace features) carries:

• can_replace_logo: bool = False — controls whether the workspace can swap the web app logo

SystemFeatureModel (system-wide features) carries:

• branding: BrandingModel — enterprise-managed fields: application_title, login_page_logo, workspace_logo, favicon (all default empty) 1

Resolution Logic (FeatureService)#

FeatureService.get_features() populates can_replace_logo in a two-stage pipeline 2:

1. Env override — _fulfill_params_from_env() sets features.can_replace_logo = dify_config.CAN_REPLACE_LOGO. This always runs first.
2. Billing override — When DEPLOYMENT_EDITION == DeploymentEdition.CLOUD, _fulfill_params_from_billing_api() overwrites the value with the billing API response, if the field is present. Billing takes precedence over the env var.

FeatureService.get_system_features() populates enterprise branding 3:

• system_features.branding.enabled is set to True only when DEPLOYMENT_EDITION == DeploymentEdition.ENTERPRISE 4
• Enterprise branding fields (applicationTitle, loginPageLogo, workspaceLogo, favicon) are then pulled from EnterpriseService.get_info() via _fulfill_params_from_enterprise()

Environment Variables#

CAN_REPLACE_LOGO can be set directly as an env var for self-hosted deployments that want logo replacement without a billing integration. When DEPLOYMENT_EDITION == DeploymentEdition.CLOUD, the billing API response overrides this env var.

DEPLOYMENT_EDITION is an enum (DeploymentEdition.COMMUNITY, DeploymentEdition.ENTERPRISE, DeploymentEdition.CLOUD) that serves as the single source of truth for deployment edition and feature gating [api/configs/deploy/init.py]. It replaces the deprecated ENTERPRISE_ENABLED and BILLING_ENABLED flags.

Migration note: ENTERPRISE_ENABLED and BILLING_ENABLED have been deprecated and consolidated into DEPLOYMENT_EDITION as the single source of truth for edition-based feature gating. Set DEPLOYMENT_EDITION=ENTERPRISE for enterprise deployments or DEPLOYMENT_EDITION=CLOUD for cloud deployments with billing.

Version note: PR #38126 fixed CAN_REPLACE_LOGO default from True → False (previously set to True in PR #37452). The current correct default is False. 5

Access Control & API#

The workspace_custom billing check in cloud_edition_billing_resource_check gates both the custom-config endpoint and logo upload: if features.can_replace_logo is falsy, the request is rejected with HTTP 403 6.

Two console API endpoints handle workspace branding 7:

• POST /workspaces/custom-config — stores remove_webapp_brand and replace_webapp_logo on the Tenant model's custom_config_dict 8
• POST /workspaces/custom-config/webapp-logo/upload — accepts SVG or PNG files only; returns the uploaded file ID 9

Both endpoints are decorated with @cloud_edition_billing_resource_check("workspace_custom"), meaning they fail with 403 if can_replace_logo is False when DEPLOYMENT_EDITION == DeploymentEdition.CLOUD.

Summary of Gating#