Dosu LogoDosu Logo
Ask
Join our Discord
Organization avatar
difyPublic
Dify
Documentsdify
App Publishing and Embedding
App Publishing and Embedding
Type
Topic
Status
Published
Created
Jul 29, 2026
Updated
Sep 2, 2026
Created by
Dosu Bot
Updated by
Dosu Bot

App Publishing and Embedding#

Every Dify app that is made publicly accessible is backed by a Site record. The Site stores the access token (code), display customizations, and access-control policy that governs how users reach the published web app. This article covers the data model, the API endpoints that manage it, and the frontend that generates embed snippets.


The Site Model#

Defined in api/models/model.py, the Site table maps 1-to-1 with an App.

Key columns :

ColumnTypeNotes
app_idUUID FKLinks site to its App
codeString(255)16-char opaque access token; indexed with status
title, descriptionString / LongTextDisplayed on the public page
icon_type, icon, icon_backgroundStringBranding
default_languageStringUI locale for the public page
chat_color_theme / chat_color_theme_invertedString / BooleanTheme accent color
customize_domainStringCustom domain (if configured)
copyright, privacy_policyStringFooter links
input_placeholder, custom_disclaimerString / LongTextInput hints; disclaimer max 512 chars
customize_token_strategyEnummust / allow / not_allow — controls whether end-users must provide their own API key
prompt_publicBooleanWhether the system prompt is visible to end-users
show_workflow_stepsBooleandefault true — show workflow execution steps
use_icon_as_answer_iconBooleandefault false
statusEnumnormal / (disabled) — tracks whether site is active

The code column is set by Site.generate_code(16, session=session), which loops until a globally unique 16-character string is found. The app_base_url property resolves the public URL from APP_WEB_URL or the incoming request root .


API Endpoints#

Enable / Disable the site#

POST /apps/<app_id>/site-enable
Takes { enable_site: bool }. Requires APP_RELEASE_AND_VERSION RBAC permission. Delegates to AppService.update_app_site_status. Returns the full AppDetail response.

Update site settings#

POST /apps/<app_id>/site
Accepts an AppSiteUpdatePayload with all customizable fields as optional. Each non-None field is patched onto the Site row in place. Requires edit permission + APP_RELEASE_AND_VERSION RBAC.

Updatable fields via this endpoint :
title, icon_type, icon, icon_background, description, default_language, chat_color_theme, chat_color_theme_inverted, customize_domain, copyright, privacy_policy, input_placeholder, custom_disclaimer, customize_token_strategy, prompt_public, show_workflow_steps, use_icon_as_answer_icon.

Reset access token#

POST /apps/<app_id>/site/access-token-reset
Generates a new code via Site.generate_code(16). Requires admin or owner (is_admin_or_owner_required) plus APP_RELEASE_AND_VERSION RBAC — intentionally stricter than the settings update endpoint.

Frontend service layer#

The frontend invokes these endpoints through oRPC TanStack Query contracts defined in web/service/client.ts:

  • Site enable/disable — consoleQuery.apps.byAppId.siteEnable.post.mutationOptions() takes { params: { app_id: string }, body: { enable_site: boolean } }. Components call useMutation with these options; the mutation automatically invalidates the app detail query on success via its onSettled callback.

  • Site access token reset — consoleQuery.apps.byAppId.site.accessTokenReset.post.mutationOptions() takes { params: { app_id: string } }. The mutation invalidates the app detail query on success; components supply their own onSuccess callback to coexist with the shared invalidation logic.

  • API enable/disable — consoleQuery.apps.byAppId.apiEnable.post.mutationOptions() takes { params: { app_id: string }, body: { enable_api: boolean } }. The mutation invalidates the app detail query on success.

Mutation ownership: the individual access-point cards (web-app-card.tsx, service-api-card.tsx) manage their own pending state via useMutation, while shared invalidation is configured in the mutation defaults in client.ts.

The settings update endpoint is still wrapped by updateAppSiteConfig in web/service/apps.ts; that operation has not yet migrated to the oRPC contract pattern.


Embedding Options UI#

The Embedded component in web/app/components/app/overview/embedded/index.tsx is a Dialog that the app overview page opens. It renders three embed options via the OPTION_KEYS = ['iframe', 'scripts', 'chromePlugin'] constant .

All snippet generation lives in web/app/components/app/overview/app-card-utils.ts:

OptionGeneratorOutput
iframegetEmbeddedIframeSnippet(iframeUrl)Plain <iframe src="..."> tag with allow="microphone;clipboard-write"
scriptsgetEmbeddedScriptSnippet({url, token, ...})window.difyChatbotConfig object + <script src=".../embed.min.js"> + CSS override block
chromePlugingetChromePluginContent(iframeUrl)Just the chatbot URL string for the Dify Chatbot Chrome extension

The iframe URL is built by buildEmbeddedIframeUrl : it assembles {appBaseUrl}/{webAppRoute}/{accessToken} and encodes any workflow hidden-start variables as gzip+base64 query parameters via compressAndEncodeBase64 .

The EmbeddedWebAppRoute type constrains the route segment to 'chatbot' | 'agent' , so the embed dialog works for both chatbot and agent-type apps. Workflow apps with hidden start-node variables expose a collapsible input panel inside the dialog so those values can be baked into the generated snippet .


Related Articles#

  • Chatbot Widget Embedding — deep-dive into embed.js, window.difyChatbotConfig, and postMessage protocol
  • Iframe Embedding Security — X-Frame-Options, CSP, and NEXT_PUBLIC_ALLOW_EMBED
  • JWT Authentication — how the Site.code (access token) is exchanged for a passport JWT at /api/passport
Documents
Account Activity Tracking
Agent API Routes
Agent App Architecture
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent App Event Architecture
Agent App Input Variables
Agent Cost and Usage Tracking
Agent File Handling
Agent File Upload Configuration
Agent Icon Data Model
Agent Log Event Pipeline
Agent Message History
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Model Settings
Agent Node Data Models
Agent Response Schema
Agent Runtime
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Runtime Backend Initialization
Agent Runtime Layer Provider Registration
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Sandbox SSRF Allowlisting
Agent Shell Layer
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent Strategy Plugin Architecture
Agent V2 Architecture
Dify Agent Server 模块分析 (Commit 55f95dbc)
Agent V2 Configure Interface
Agent V2 Feature Flags
Agent V2 File and Vision Handling
Agent V2 Variable System
Agent Workflow Node Variable References
API Documentation Pipeline
App Mode Configuration
App Publishing and Embedding
Audio to Text API
Auth Route Architecture
Automatic Rule Generation
Avatar Management
Branding Customization
Browser Tab and State Management
Builtin Tool Provider Credentials
Celery Task Resilience
Chat Action Bar Mobile Visibility
Chat Avatar Rendering
Chatbot Conversation State Recovery
Chatbot Widget Embedding
Collaborative Workflow Editing
Console API DELETE Request Handling
Console Authentication
Conversation Deep-Linking
Credential Encryption and Secret Management
CSV Data Ingestion
Custom Tool Authentication
Custom Tool HTTP Timeout Configuration
Custom Tool OpenAPI Integration
Data Export
Database Migration System
Database Session Management
Database Transaction Isolation
Dataset Batch Import
Dataset Deletion
Dataset Permission Model
Dataset Segmentation Configuration
Dependency Injection and Testability
Dify Agent Server 模块分析 (Commit 55f95dbc)
Dify Agent Monorepo Structure
Dify Agent Server 模块分析 (Commit 55f95dbc)
Dify Cloud Billing
Dify OpenAPI
difyctl CLI
Docker Container Security
Docker Deployment and Upgrades
Docker Frontend Configuration
Docker Image Publishing
Docker Networking
Docker Storage and Permissions
Document Indexing Operations
DocumentSegment Position Assignment
Draft Variable Storage Cleanup
Edition-Based Feature Gating
Elasticsearch Integration
Embedding Cache Integrity
Excel Extractor
External Knowledge Integration
Extractor Encoding Fallback
File Access Control
File Array Handling
File Download Architecture
File Download Security
File Storage Synchronization
File Upload and Download Integrity
File Upload Configuration
File Upload Processing
File URL Resolution
Flask Application Architecture
Flask Blueprint and Route Registration
Graph Streaming Infrastructure
Home Directory Management
HTTP Request Node
HTTP Request Node Key-Value Editor
HTTP Request Node Size Constraints
httpx and Gevent Compatibility
Human Input Node
Hybrid Search
Icon URL Resolution
Iframe Embedding Security
Internationalization and Locale Management
Jina Reranker Integration
JSON-in-Markdown Parsing
JWT Authentication
Keyboard Shortcut Management
Keyword Moderation
Knowledge Base API
Knowledge Base Document Processing
Knowledge Base Metadata Filtering
Knowledge Base Summarization Pipeline
Langfuse Integration
Lexical Editor Integration
LLM Provider Message Validation
LLM Structured Output
Local Development Configuration
Local Embedding Model Deployment
Log Filtering
Markdown Extractor Heading Parsing
Markdown Rendering
Marketplace Plugin Filtering
MCP Client Transport and Connectivity
MCP Protocol Integration for Dify Workflows
MCP OAuth Integration
MCP Protocol Integration
MCP Protocol Integration for Dify Workflows
MCP Provider Architecture
MCP Tool Content Processing
MCP Tool Integration
MCP Protocol Integration for Dify Workflows
MCP Tool Parameter Binding
MCP Tool Provider Management
Messaging Platform Integration
Milvus Integration
Model Provider Error Handling
Monaco Editor Integration
Multi-Tenant Context Propagation
Multimodal Knowledge Base Support
Multimodal Prompt Delivery
N+1 Query Optimization
Next.js Routing and Redirects
Next.js SSR Authentication
Nginx Reverse Proxy Configuration
Notion Extractor Table Parsing
NumPy CPU Compatibility
OAuth Login Flow
Observability and Tracing
OpenAI-Compatible Server Integration
OpenAPI Spec Accuracy
OpenDAL Storage Backend
Ops Trace Data Models
Oracle Database Connectivity
Parallel Workflow Execution
Parent-Child Retrieval Architecture
Plugin API Key Configuration
Plugin Architecture
Plugin Credential Management
Plugin Daemon Architecture
Plugin Daemon Communication
Plugin Daemon Model Parameter Handling
Plugin Database Integrity
Plugin Error Handling
Plugin File Handling
Plugin Lifecycle Management
Plugin Marketplace Connectivity
Plugin Model Caching
Plugin Permissions
Plugin Storage Configuration
Plugin System Timeouts
Plugin Taxonomy and Validation
Plugin Trigger OAuth Refresh
Private Address Detection
Provider Model & Credential Management
Pyrefly Type Checker
RAG Web Crawling Providers
Rate Limiting and Concurrency Control
RBAC Initialization
RBAC Permission Key Lookup
Reasoning Model Integration
Reasoning Tag Filtering
Redis Connection Management
Redis Streaming Resilience
Release Breaking Changes
Remote File Fetching
Remote File Handling and Validation
Retrieval Filtering and Scoring
RTL Locale Support
Sandbox Code Execution
Sandbox Network Isolation
Segment Update and Attachment Lifecycle
Server Deployment Configuration
Service API Error Handling
Service API Pagination
Shell Provider Lifecycle
Snippet Variable Handling
SQLite Test Infrastructure
SSE Stream Lifecycle
SSE Stream Terminal Event Delivery
SSR Data Fetching
SSRF Proxy
Suggested Questions After Answer
Summary Index
Tenant-Isolated Document Indexing Queue
Test Doubles and In-Memory Repositories
TiDB Vector Full-Text Search
Time Tools
Timestamp Management
Tool File URL Signing
Tool Node Input Validation
Tool Provider Authorization
Trace Task Pipeline
User and Tenant Context Propagation
Dify Agent Server 模块分析 (Commit 55f95dbc)
User Roles and Permissions
Variable Pool Falsy Value Handling
Variable Resolution and Template Substitution
Vector Database Plugin Architecture
Vector Store Integration
Weaviate Vector Store
Web Container Docker Configuration
Webhook Trigger System
WebSocket Service Architecture
Word Document Extraction
Workflow Agent Node Configuration
Workflow and Agent Composition
Workflow Conditional Branching
Workflow Container Nodes
Workflow Conversation State Management
Workflow Draft Synchronization
Workflow Execution Dispatch
Dify Agent Server 模块分析 (Commit 55f95dbc)
Workflow Execution Persistence
Workflow Fail Branch Architecture
Workflow File Handling
Workflow Graph Validation
Workflow Iteration Node Execution
Workflow LLM Node Configuration
Workflow Memory Management
Workflow Node Canvas Summary Rendering
Workflow Node Versioning
Workflow Pause-Resume State Management
Workflow Resume Architecture
Workflow Run State Management
Workflow Schedule Triggers
Workflow Test Run Execution
Workflow Timeout and Execution Limits
Workflow Tool Visibility and Access Control
Workflow Trigger Log Lifecycle
Workflow Variable Size Management