Introducing a new way to review your PRs.

Read the announcement

twentyhq / twenty

The open alternative to Salesforce, designed for AI.

View on GitHub

22 documents · Updated Nov 20, 2026

docs / extension-integrations

Marketplace, Zapier, and external extensions

Twenty connects outside services to a workspace through three related surfaces: the marketplace for finding and installing apps, Zapier for record automation, and the SDK for building apps with data, server actions, connections, and user interface parts. These surfaces use stable app identity and metadata contracts. They keep external code and workflows behind defined host APIs.

Extension surface

The extension surface separates app discovery, workflow automation, and app development. Each surface has a different relationship with workspace data:

SurfaceMain goalWorkspace boundary
MarketplaceFind, assess, install, and update appsCatalog identity, release metadata, trust state, and declared access
ZapierMove record data between Twenty and other servicesAPI-key access, workspace metadata, record actions, and webhooks
SDK applicationsAdd data, server actions, connections, messaging, pages, agents, and app UIApplication manifest, declared capabilities, runtime API, and app assets
Front component rendererShow app UI inside TwentyIsolated execution, host actions, remote elements, and network policy

The marketplace and Zapier depend on stable app and API contracts. SDK apps declare those contracts before the platform installs or runs them. Their server and UI parts use narrow host APIs instead of the full Twenty client.

Marketplace integration

The marketplace turns published app metadata into a catalog that users can inspect and install. A shared application registration links the catalog entry to its source, version, manifest, support data, OAuth data, and workspace state. marketplace-catalog-sync.service.ts application-registration.entity.ts

Catalog discovery

Catalog refresh reads app packages from the configured registry and records their identity, manifest, version, and display assets. Refresh is a repeatable discovery action. It does not install an app by itself. The marketplace module groups catalog sync, package access, registration, cache, permissions, and public query services behind one application boundary. marketplace.service.ts marketplace.module.ts

First-party apps use shared universal identifiers so marketplace curation and billing rules refer to the same app identity. A featured-app list controls selected catalog order. A separate exemption list prevents high-frequency first-party apps from consuming the normal credit allowance for each record or event invocation. marketplace-featured-applications.constant.ts marketplace-billing-exempt-applications.constant.ts TwentyPublicAppUniversalIdentifiers.ts

The catalog flow moves from a package registry to application registration and then to public or workspace queries:

flowchart LR
  R[Package registry] --> S[Catalog refresh]
  S --> M[Manifest and display assets]
  M --> A[Application registration]
  A --> Q[Workspace and public queries]
  Q --> U[Marketplace]

References: packages/…/marketplace.service.ts• L46-149 packages/…/marketplace-catalog-sync.service.ts• L21-105 packages/…/marketplace.module.ts• L20-42 packages/…/marketplace-featured-applications.constant.ts• L1-44 packages/…/marketplace-billing-exempt-applications.constant.ts• L1-12 packages/…/TwentyPublicAppUniversalIdentifiers.ts• L1-11

Trust and permission review

Marketplace exposure and trust are separate decisions. isListed controls whether public detail can return an app. isVetted controls the default public catalog filter. Workspace users can still resolve selected app identifiers outside that public filter. marketplace-public.resolver.ts marketplace-query.service.ts

Before install, Twenty presents the app's requested capabilities, billing behavior, and default-role access. The summary groups record access by read, write, and delete rights. It names affected objects when workspace metadata can resolve them. Permissions on objects owned by the app are not repeated as workspace access. Unknown permission identifiers are ignored rather than shown as trusted access. SettingsApplicationInstallPermissionValidationModal.tsx buildPermissionSummaryFromRoleManifest.ts buildObjectRecordsPermissionSummary.ts

Marketplace detail data gives the client explicit app information for this review. It includes source and version data, support and pricing information, roles, objects, requested capabilities, requested iframe media permissions, and whether the app bills credits. The query service builds these values from the registration and manifest so the catalog view and install review use the same app contract. marketplaceAppDetailFragment.ts marketplace-app-detail.dto.ts

The marketplace also supports connection links for external services. A link can contain a server placeholder for an MCP connection; the client replaces it with the workspace MCP URL and URL-encodes that value. A link without the placeholder remains unchanged. getMarketplaceAppConnectLink.ts

System permission identifiers map to plain user-facing summaries. The same review model covers broad workspace rights, file actions, connected accounts, external requests, AI actions, and app management. An app that is not listed receives a visible warning before install. PermissionFlagSummaryConfigs.ts PermissionFlagTypeByUniversalIdentifier.ts

References: packages/…/marketplaceAppDetailFragment.ts• L3-63 packages/…/marketplaceAppFragment.ts• L3-14 packages/…/SettingsApplicationInstallPermissionValidationModal.tsx• L136-297 packages/…/buildPermissionSummaryFromRoleManifest.ts• L19-79 packages/…/buildObjectRecordsPermissionSummary.ts• L74-143 packages/…/buildRoleManifestFromMarketplaceAppRole.ts• L4-36 packages/…/getMarketplaceAppConnectLink.ts• L4-14 packages/…/PermissionFlagSummaryConfigs.ts• L32-145 packages/…/marketplace-app-detail.dto.ts• L22-145

Installation and upgrades

Marketplace installation is an asynchronous workspace action. The client sends an app universal identifier, receives a job identifier, and follows progress until success or failure. A reload checks the server for an active job, and a reconnect checks the final state if the event stream was unavailable. On success, the client reloads the installed application and its declared extension state before updating workspace state. useInstallMarketplaceApp.ts findInstallApplicationJobStatus.ts applicationFragment.ts

The installed application state covers the registration version and source plus the app's variables, front components, menus, objects, agents, and logic functions. The client therefore refreshes one application contract after the job completes instead of treating installation as only a catalog change. applicationFragment.ts

Upgrades use the same job boundary with a target version. Both actions expose progress and surface the server failure reason. This keeps long-running package work out of the browser request while keeping the user view current. useUpgradeApplication.ts findUpgradeApplicationJobStatus.ts

The install flow is permission-first and job-based:

sequenceDiagram
  participant U as User
  participant C as Twenty client
  participant J as Install or upgrade job
  participant A as Application state
  U->>C: Review access and request app change
  C->>J: Start change with app identifier and version when needed
  J-->>C: Job identifier
  C->>J: Track active or restored job
  J-->>C: Progress, success, or failure
  C->>A: Reload app and declared extension state after success
  A-->>U: Updated application view

References: packages/…/SettingsApplicationInstallPermissionValidationModal.tsx• L191-297 packages/…/useInstallMarketplaceApp.ts• L44-172 packages/…/useUpgradeApplication.ts• L33-121 packages/…/findInstallApplicationJobStatus.ts• L3-17 packages/…/findUpgradeApplicationJobStatus.ts• L3-17 packages/…/applicationFragment.ts• L6-92

Capability grants

Some front-component capabilities need a later workspace decision at run time. For example, a media request opens a review dialog and grants the requested capabilities to the whole workspace only when an app manager authorizes it. A denied or interrupted request does not grant access. FrontComponentMediaPermissionModal.tsx

The host also shows a compact media-session indicator while an app records or waits for permission. It groups sessions by application and lets the user review or stop the sessions from the popover. Active sessions use an “Apps recording” state. Pending sessions use a “Recording requests” state. FrontComponentMediaSessionIndicator.tsx

References: packages/…/FrontComponentMediaPermissionModal.tsx• L43-81 packages/…/FrontComponentMediaPermissionModal.tsx• L95-129 packages/…/FrontComponentMediaSessionIndicator.tsx• L36-81

Zapier integration

The Twenty Zapier app gives Zapier a metadata-aware connector for record changes and record events. It uses a workspace API key and can target either the hosted service or a self-hosted Twenty URL. authentication.ts requestDb.ts

Authentication and record actions

Zapier tests a connection by reading the current workspace through the metadata API. The same bearer key and selected base URL serve later record and webhook requests. Zapier reads active objects and fields before it builds action inputs, so one connector can work with standard and custom objects. Create, update, and delete actions then map to Twenty record mutations. authentication.ts crud_record.ts

References: packages/…/authentication.ts• L5-39 packages/…/requestDb.ts• L5-105 packages/…/find_object_names_singular.ts• L5-30 packages/…/crud_record.ts• L25-159

Record event delivery

Zapier uses Twenty webhooks as the event link. A selected object and event type create a webhook subscription. Created, updated, and deleted events become Zapier trigger output. Update events include changed fields, and unsubscribe removes the matching webhook. triggers.utils.ts trigger_record.ts

sequenceDiagram
  participant Z as Zapier
  participant T as Twenty API
  participant W as Twenty webhook
  Z->>T: Test API-key connection
  Z->>T: Read object and field metadata
  Z->>T: Create webhook for object event
  T-->>W: Record event
  W-->>Z: Record and changed fields
  Z->>T: Create, update, or delete record

References: packages/…/triggers.utils.ts• L16-70 packages/…/trigger_record.ts• L20-58 packages/…/crud_record.ts• L101-159

SDK extension boundary

The twenty-sdk package is the application authoring and runtime SDK for Twenty CRM. It exposes declarations, front-component helpers, logic-function helpers, inbox actions, billing, utilities, and renderer integration through separate package entry points. The standalone twenty package owns app scaffolding, builds, authentication, sync, and publishing. The SDK and the CLI therefore serve different parts of the app life cycle. README.md package.json

Application declarations

An app declaration describes identity and the workspace capabilities that the app needs. These can include data objects, fields, related record paths, roles, page parts, page layout widgets, logic functions, workflows, agents, connection and messaging providers, MCP servers, front components, inbox actions, translations, health checks, skills, validation rules, settings menu items, and billing. The declarations form the app contract that the host can install and run. index.ts loose-shared-types.type.ts

Stable universal identifiers let later app changes address the same declared entities. The SDK validates core identity and relationship rules before the host accepts the contract. For example, related record paths require a starting field and cannot skip an intermediate relation. Standalone page layout widgets must name their target tab and position because their tab is not part of the same manifest. Workflows also reject unsupported steps and cycles. A workflow AI step either carries its own generation settings or points to an app agent when it needs a conversation. Agents can declare model capabilities and bounded database or scheduled triggers. define-related-record-path.ts define-page-layout-widget.ts validate-standalone-page-layout-widget-placement.ts define-workflow.spec.ts define-agent.ts

Validation rules can use the SDK expression builder for field, prior-value, time, comparison, arithmetic, and logical values. The builder produces the string form that the host validates, so a declaration can stay typed while still crossing the manifest boundary as one expression. rule-expression.ts define-validation-rule.ts

Application assets belong to the app package. The SDK keeps relative bundled paths and warns on deprecated names. It ignores external absolute URLs for logos and gallery images so the app manifest does not depend on an uncontrolled asset host. normalize-application-assets.ts normalize-application-assets.test.ts

Conditional availability expressions form a separate declaration boundary. The SDK exports named context values and operators for expressions, but their placeholders fail if app code tries to use them as normal run-time values. The shared name list keeps the expression surface aligned with the exported variables. conditional-availability-variable-names.ts conditional-availability-variables.ts conditional-availability-variables.spec.ts

Application configuration also carries user or workspace variables and billing declarations. It warns about deprecated role configuration and rejects invalid variable scopes, unknown billing types, invalid recurring charges, and name collisions between recurring charges and usage operations. Apps can also declare exact HTTPS origins for iframe microphone or camera access. define-application.ts define-app.spec.ts

Health checks are app-owned status actions. An app can define one check for the workspace or opt into a member-aware check that receives a workspace member identity. The declaration keeps these two call shapes distinct so the host knows whether user context is required. define-health-check.ts health-check-logic-function-config.ts

References: packages/…/index.ts• L1-266 packages/…/loose-shared-types.type.ts• L19-96 packages/…/define-application.ts• L23-239 packages/…/normalize-application-assets.ts• L5-64 packages/…/normalize-application-assets.test.ts• L5-83 packages/…/conditional-availability-variable-names.ts• L1-34 packages/…/conditional-availability-variables.ts• L9-29 packages/…/define-page-layout-widget.ts• L8-15 packages/…/define-workflow.spec.ts• L124-237 packages/…/define-health-check.ts• L13-45 packages/…/define-agent.ts• L27-175 packages/…/rule-expression.ts• L7-103 packages/…/define-validation-rule.ts• L8-46

SDK package boundary

The SDK package is installed with an app and supplies the public APIs used by app code. The global CLI is a separate tool that creates the app and manages its connection to a Twenty workspace. This split keeps app runtime contracts independent from developer workflow commands. README.md package.json

The package publishes stable subpaths for declarations, front components, logic functions, billing, utilities, and renderer support. These entry points define the boundary that app code can rely on rather than importing internal SDK modules. The changelog is the source for compatibility changes between the SDK, client package, CLI, and Twenty server. package.json CHANGELOG.md

Recent SDK changes make compatibility part of this boundary. API-key connection providers, event-based triggers, inbox actions, selected-record context, and batch jobs add public contracts. Direct file-storage uploads replace older multipart fallbacks for message and application files. Apps should treat the SDK changelog as the source for breaking contract changes when they upgrade. CHANGELOG.md

References: packages/…/README.md• L15-32 packages/…/package.json• L8-61 packages/…/CHANGELOG.md• L7-150

Connection providers and runtime access

An SDK connection provider describes how an app links a workspace or user to an outside account. The provider boundary supports OAuth, OAuth discovery, custom callbacks, and API-key entry. Each provider uses a stable UUID and a URL-safe name. OAuth providers declare endpoints, scopes, and app server variables. Custom providers declare authorization and callback logic functions. API-key providers can identify an account after the member enters a key. define-connection-provider.ts define-connection-provider.spec.ts

At run time, app logic can list or fetch connections through the host API. A request first uses the request user's personal connection. If none exists, it can use a workspace-shared connection. Scheduled and database-event work can use the shared connection without user context. A connection marked as needing authorization raises an auth failure so the platform can ask the user to reconnect. index.ts list-connections.ts get-connection.ts

The host protects connection management with separate permission checks for personal accounts and workspace-shared accounts. OAuth authorization uses short-lived signed state and can use PKCE. The callback exchanges the code, identifies the external account, stores encrypted credentials, and runs the app's connect hook. Custom providers can receive a GET redirect callback or a POST notification callback through the same state boundary. app-connection-access.service.ts connection-provider-oauth-flow.service.ts connection-provider-custom.controller.ts

Token responses must contain an access token. The host accepts numeric or string expires_in values and can use a JWT exp claim when the provider omits expires_in. Refresh keeps the old refresh token when a provider does not rotate it. A token-endpoint client error asks the user to reconnect, while server and transport errors remain transient. parse-token-response.util.ts parse-access-token-expires-at.util.ts app-oauth-refresh-tokens.service.ts

The provider declaration and runtime selection form one boundary:

flowchart LR
  D[SDK provider declaration] --> O[OAuth, discovery, custom, or API-key account connection]
  O --> P[Personal connection when available]
  O --> W[Workspace connection as fallback]
  P --> L[App logic]
  W --> L
  L --> E[Reconnect signal when authorization failed]

References: packages/…/define-connection-provider.ts• L12-17 packages/…/define-connection-provider.ts• L73-175 packages/…/define-connection-provider.spec.ts• L135-253 packages/…/index.ts• L45-64 packages/…/list-connections.ts• L23-42 packages/…/get-connection.ts• L24-38 packages/…/app-connection-access.service.ts• L17-57 packages/…/connection-provider-oauth-flow.service.ts• L46-197 packages/…/connection-provider-custom.controller.ts• L34-129 packages/…/parse-token-response.util.ts• L7-33 packages/…/app-oauth-refresh-tokens.service.ts• L28-78

Logic-function runtime

Logic functions are the server-side action boundary for an app. Their declarations select route, schedule, database-event, tool, health-check, or install lifecycle triggers. Runtime helpers expose approved host services such as connections, jobs, messaging, inbox threads, agents, timeline activities, storage, key-value state, responses, billing, and credit checks. logic-function/index.ts logic-function-config.ts

Logic functions can enqueue one or many runs of a declared logic function through the metadata API. The batch form takes payloads for one target function and returns job identifiers, per-job size data, and the remaining byte allowance. Retry and delay options apply to every run in the batch. The older one-job helper remains available as a compatibility path. enqueue-jobs.ts enqueueJobType.ts

The runtime provides an app key-value store for state that must survive one run. Workspace scope is the default, while server scope supports shared app state. Calls use the app runtime API and fail with a clear error when the runtime URL or token is missing. kv.ts get-application-api-config-or-throw.util.ts

The running app receives host credentials and an API URL. The host remains responsible for authorization and final billing decisions. App helpers can check credit availability before expensive work and can report declared operations or platform usage categories after work. Availability checks fail open on missing or bad responses. Billing charges are best effort: without runtime credentials or when the billing endpoint fails, the app logs the problem and the app action continues. get-application-api-config-or-throw.util.ts get-credit-availability.ts charge-credits.ts

Calls that act as the triggering user can use a delegated caller token. Application-owned calls use the application token. Logic functions can also build a host server-route URL only when they run inside an application runtime. get-application-api-config-or-throw.util.ts get-server-route-url.ts

References: packages/…/index.ts• L38-141 packages/…/logic-function-config.ts• L9-45 packages/…/enqueue-jobs.ts• L1-25 packages/…/enqueueJobType.ts• L1-41 packages/…/kv.ts• L34-92 packages/…/get-credit-availability.ts• L42-88 packages/…/get-server-route-url.ts• L4-16

Messaging extensions

Messaging helpers let an app ingest provider messages and attach them to Twenty threads. Message identity, thread grouping, participant links, folders, and attachment state form the contract that makes repeated provider delivery safe. A messaging provider must link to an app connection provider. Send and mark-read logic functions are optional, so an app can support ingestion without outbound actions. define-messaging-provider.ts define-messaging-provider.spec.ts ingest-messages.ts

An app can upload a message attachment through the file-storage boundary and pass the returned file reference to ingestMessages. The result reports whether the stored message already has attachments, so a provider can avoid repeating downloads during a redelivery. Attachment uploads need the app's file permission and use the application runtime token. upload-message-attachment.ts upload-message-attachment.spec.ts

Inbox helpers let an app send a message, link or unlink a record from a thread, archive a thread for named members, and create canonical mention references. Member and record helpers resolve the label that the inbox displays. The assistant mention uses the same canonical record-reference token as the inbox composer, so the saved message keeps the assistant identity instead of plain display text. logic-function/index.ts archive-inbox-thread.ts inbox-mention.ts

References: packages/…/define-messaging-provider.ts• L11-78 packages/…/define-messaging-provider.spec.ts• L20-73 packages/…/ingest-messages.ts• L7-39 packages/…/ingest-message.type.ts• L3-41 packages/…/upload-message-attachment.ts• L10-46 packages/…/index.ts• L105-115 packages/…/archive-inbox-thread.ts• L4-12

AI runtime

The SDK gives logic functions a bounded way to run AI work and continue agent conversations. An app can start an agent run, read conversation history, follow live conversation events, or call text and structured generation. These calls use the app runtime API and preserve the caller identity for operations that act on behalf of the triggering user. logic-function/index.ts run-agent.ts ai.ts

Conversation streams use server-sent events. History includes both stored messages and any stream chunks needed to resume a reply. The stream ends on a server completion event, while an early close tells the app to read history and subscribe again. Optional generation callbacks receive chunks in order and stop when the run finishes or the caller aborts. list-conversation-messages.ts stream-conversation.ts stream-agent-chat-events.util.ts ai.ts

The SDK sends these requests to the workspace metadata API with an injected runtime token. Application-owned calls prefer the application token. Calls that act as the triggering user prefer the delegated caller token. Missing runtime configuration or API errors stop the request with a clear error. get-application-api-config-or-throw.util.ts get-application-access-token.ts post-graphql-request.util.ts

References: packages/…/index.ts• L88-103 packages/…/run-agent.ts• L23-42 packages/…/list-conversation-messages.ts• L12-78 packages/…/stream-conversation.ts• L6-28 packages/…/ai.ts• L116-225 packages/…/stream-agent-chat-events.util.ts• L85-182 packages/…/get-application-api-config-or-throw.util.ts• L13-34 packages/…/post-graphql-request.util.ts• L3-53

Front-component contract

A front component is an app-provided UI part that Twenty can place in an app page, record page, settings area, or widget. The host gives it a narrow execution context rather than full client state. The context includes app and user identity, selected record IDs, a select-all filter when present, selected object metadata, timeline or tool context, locale, color scheme, and the current browser location. The SDK hook subscribes to host context changes and updates a component only when its selected value changes. FrontComponentExecutionContext.ts useFrontComponentExecutionContext.ts useLocation.ts

Host communication exposes typed actions for navigation, side panels, confirmation, notifications, progress, clipboard, file upload, storage, inbox messages and thread actions, and access-token refresh. Record navigation follows the workspace's page or side-panel preference and rejects routes that the host cannot render. File upload is limited to valid files fields. Clipboard calls have size and rate limits. Signed-in storage is isolated by application and user. frontComponentHostCommunicationApi.ts useFrontComponentExecutionContext.ts useFrontComponentExecutionContext.ts

Front components can also work with inbox threads through the public SDK boundary. They can send an app message, link or unlink a record, archive a thread for selected members, and create member, record, or assistant mention tokens without placing a logic function between the UI and the host API. These actions remain subject to the member and application permissions enforced by the host. index.ts send-inbox-message.ts archive-inbox-thread.ts

Select-all actions use the host-provided filter even when the selected ID list is empty. This keeps a component from treating an intentional full-set selection as no selection. A component can also read the selected object's identity through the public metadata hook. useSelectedRecordsFilter.ts useSelectedObjectMetadata.ts useFrontComponentExecutionContext.test.tsx

References: packages/…/define-front-component.ts• L5-26 packages/…/index.ts• L1-91 packages/…/FrontComponentExecutionContext.ts• L8-30 packages/…/useFrontComponentExecutionContext.ts• L10-41 packages/…/useSelectedRecordsFilter.ts• L1-12 packages/…/useSelectedObjectMetadata.ts• L1-13 packages/…/frontComponentHostCommunicationApi.ts• L11-182 packages/…/useFrontComponentExecutionContext.ts• L458-482 packages/…/useFrontComponentExecutionContext.ts• L492-640 packages/…/archive-inbox-thread.ts• L4-12

Renderer build contract

The SDK exposes the build boundary for front components as a public renderer subpath. It prepares app UI for the host's remote-element worker model and can share approved dependency exports with the renderer. The boundary supports the app's React-style source model while keeping renderer-specific transforms outside app code. package.json get-front-component-build-plugins.ts

The build contract covers the main renderer concerns as one pipeline:

ConcernBoundary purpose
Component entryTurns the declared front component into the worker entry point
JSX runtimeMaps app JSX behavior to remote DOM worker output
React and Preact choiceLets supported app code use the selected UI runtime
CSSCarries component styles into the rendered app
Shared dependenciesExposes only the exports listed by the host build context

The shared dependency shim is a shared build service. The SDK supplies renderer plugins, while twenty-shared supplies the common bridge used by the SDK and other build consumers. create-shared-dependencies-shim-plugin.ts shared-dependencies-build-context.type.ts

The build step unwraps a default defineFrontComponent or defineSettingsFrontComponent export into a direct renderer entry. It supports both inline component expressions and named component values. The renderer waits for the first commit, rejects a failed or stalled initial mount, and reports later render errors through the worker boundary. unwrap-define-front-component-to-direct-export.spec.ts

References: packages/…/package.json• L52-61 packages/…/get-front-component-build-plugins.ts• L14-37 packages/…/create-shared-dependencies-shim-plugin.ts• L8-51 packages/…/shared-dependencies-build-context.type.ts• L1-5 packages/…/unwrap-define-front-component-to-direct-export.spec.ts• L113-281

Component renderer boundary

The component renderer is the host boundary for app UI. It runs a component in an isolated worker, supplies app and SDK bundles, renders remote elements, and exposes approved host services through a communication bridge. The host owns readiness, fallback, and error handling. FrontComponentRenderer.tsx renderFrontComponent.ts

Worker rendering

The host sends the worker component source, shared dependency sources, app variables, storage state, media capabilities, and allowed fetch origins. The worker returns remote elements instead of receiving the host DOM. The SDK adapts React and Preact output to the renderer's custom-element vocabulary so app code can use normal component patterns while the host keeps control of the DOM and event policy. HostToWorkerRenderContext.ts jsx-transform-to-remote-dom-worker-format-plugin.ts

The renderer also keeps host-owned UI outside the app event surface. Host controls are marked with a shared class so worker listeners and outside-press tracking do not treat host controls as app input. This allows menus, dialogs, and other host overlays to remain usable above an app component. FrontComponentHostUiClassName.ts isHostUiEvent.ts wrapEventHandler.ts

References: packages/…/FrontComponentRenderer.tsx• L33-153 packages/…/renderFrontComponent.ts• L20-68 packages/…/HostToWorkerRenderContext.ts• L6-21 packages/…/get-front-component-build-plugins.ts• L17-37 packages/…/FrontComponentHostUiClassName.ts• L1 packages/…/isHostUiEvent.ts• L1-10

Iframe media boundary

An app can request microphone or camera access for exact HTTPS iframe origins. The renderer does not grant that access from an app's raw allow attribute. It identifies media requests, passes only a small iframe contract to a trusted host, and renders the host-approved allow and sandbox values. Ordinary iframes stay on the native path with media explicitly disabled when no managed request exists. HostIframeElement.tsx FrontComponentIframeHostProps.ts getRequestedIframeMediaCapabilities.ts

The host boundary normalizes sensitive prop names and accepts only typed source, visibility, sandbox, and media values. It keeps ordinary HTML attributes, styles, handlers, and fallback content while replacing permission-sensitive iframe values with the trusted host result. HostSanitizedPropNames.ts normalizeHostSanitizedPropName.ts getIframeHostReactProps.ts HostIframeElement.test.tsx

References: packages/…/HostIframeElement.tsx• L15-74 packages/…/FrontComponentIframeHostContext.ts• L1-6 packages/…/FrontComponentIframeHostProps.ts• L1-14 packages/…/getRequestedIframeMediaCapabilities.ts• L5-17 packages/…/getIframeHostReactProps.ts• L1-15 packages/…/normalizeHostSanitizedPropName.ts• L1-13 packages/…/HostIframeElement.test.tsx• L15-198

Host communication and network policy

The worker uses a bridge for navigation, clipboard, confirmation, storage, media, geometry, and error reporting. Requests to approved origins use the host fetch bridge. Other requests use worker fetch. This lets the host apply policy to selected network calls without owning all worker traffic. remote-worker.ts installHostFetchProxy.ts HostFetchPolicy.ts

The event boundary forwards only serialized worker events. Bubbling events are sent once from the inner listening element. Form-control state is sent once for a native event. Host-owned UI is filtered out. Outside presses are tracked only while the worker observes them, and the bridge sends event metadata rather than the host control or its private values. wrapEventHandler.ts createHostOutsidePressController.ts trackHostOutsidePress.ts

The renderer can prevent browser page zoom for zoom gestures that start inside remote app elements. It does not block normal scrolling or gestures outside the component. Portal content remains part of the app's tracked geometry, so app controls rendered outside the main component root keep their event and zoom behavior. FrontComponentPreventPageZoomEffect.tsx twenty-ui-portals.front-component.tsx portalZoomTest.ts

flowchart LR
  H[Twenty host] -->|Render context and updates| W[Component worker]
  W -->|Remote elements| H
  W -->|Approved actions| B[Host communication bridge]
  B --> H
  W -->|Approved origins| F[Host fetch bridge]
  W -->|Other origins| N[Worker fetch]
  H -->|Serialized outside presses| W

References: packages/…/remote-worker.ts• L95-157 packages/…/installHostFetchProxy.ts• L7-31 packages/…/HostFetchPolicy.ts• L1-4 packages/…/wrapEventHandler.ts• L15-68 packages/…/createHostOutsidePressController.ts• L15-101 packages/…/trackHostOutsidePress.ts• L13-63 packages/…/FrontComponentPreventPageZoomEffect.tsx• L7-38

Marketplace discovery and SDK installation focus on app identity and declared capabilities. Zapier focuses on record exchange and event delivery. For the wider integration model, see External integrations. Account and inbox extension behavior is described in Connected accounts and messaging. Installed app state is described in Installed applications. The application delivery path is described in Application CLI. AI extension behavior is described in AI applications.

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep marketplace detail fields, role permissions, app object identifiers, capability summaries, billing summaries, iframe media permissions, connect-link placeholders, and trust warnings aligned. A drift can show users incomplete or misleading access before install.
  • Keep featured-app and billing-exempt lists on the shared first-party universal identifiers. A moved identifier can change catalog order or credit treatment for the wrong app.
  • Keep isListed checks aligned with the public isVetted filter. An app can be trusted for catalog display but still be unavailable by public detail if exposure rules drift.
  • Keep install and upgrade mutation inputs, status queries, job identifiers, event tracking, reconnect recovery, installed-state refresh, and the application fragment's declared extension fields aligned. A changed universal identifier or omitted fragment field can leave a running app change invisible or make the installed app view incomplete.
  • Keep capability grants aligned with workspace app-management permission and the request abort state. A media request must not grant access after cancellation or to an unauthorized member.
  • Keep SDK package exports, the minimum Twenty version, and changelog compatibility notes aligned with the public app import paths and the separate CLI package. A moved entry point or unsupported server can break app builds or runtime calls.
  • Keep declaration exports, universal identifiers, validation rules, and host manifest types aligned for fields, related record paths, workflows, agents, MCP servers, messaging providers, inbox actions, health checks, settings menu items, page layout widgets, conditional availability variables, and other app entities. A new entity can compile in an app while failing at registration if one boundary is missing.
  • Keep agent trigger and model capability names aligned with the host manifest. An app can pass local type checks while an unknown capability, event name, or trigger identifier is rejected at registration.
  • Keep messaging provider references aligned with the declared connection provider and optional send or mark-read logic functions. A provider can install while account linking or message delivery fails if a UUID points to the wrong app entity.
  • Keep validation-rule expression builders aligned with the host parser and compiler. A readable SDK expression can still fail when its generated source uses an unsupported function or invalid literal.
  • Keep application asset normalization aligned with the manifest and package asset rules. A change can make a catalog logo or gallery image depend on an unsupported external URL.
  • Keep standalone page layout widget tab identifiers and positions aligned with layout placement rules. A widget can pass general validation but fail because its host tab cannot infer placement.
  • Keep conditional availability exports, shared variable names, expression transforms, and runtime guards aligned. An expression can build with a name that the host cannot evaluate, or app code can accidentally try to use a declaration-only value at runtime.
  • Keep application variable scope, iframe media origin rules, and billing declaration rules aligned with the host manifest and usage breakdown. A deprecated or colliding declaration can change configuration checks or charge attribution.
  • Keep connection provider UUIDs, provider names, provider type blocks, OAuth variables, lifecycle logic-function identifiers, callback state, and declaration validation aligned. A provider can pass the app build while failing during account linking.
  • Keep connection permissions, personal-versus-workspace visibility, account identity, encrypted token storage, expiry parsing, refresh fallback, and reconnect errors aligned. A provider can work on first connect but fail after token expiry.
  • Keep message attachment file-field identity, upload-file input shape, storage completion, attachment payloads, ingest limits, and hasAttachments results aligned. A provider can ingest messages while losing attachments or downloading them again on redelivery.
  • Keep inbox mention token formats, resolved labels, archive inputs, and assistant identity aligned with the inbox composer and thread state. A display-only string or wrong member list can save a message while leaving the thread state wrong.
  • Keep logic-function AI exports, metadata GraphQL shapes, runtime token selection, stream event types, resume data, abort behavior, and caller identity aligned. A generated result can succeed while live chunks or user-scoped access fail.
  • Keep batch job inputs, payload limits, retry and delay options, result fields, and the metadata API version aligned. A helper can report success while some intended runs are not accepted or cannot be tracked.
  • Keep key-value scopes, runtime API URL selection, application tokens, and GraphQL shapes aligned. App state can appear missing when a scope or runtime endpoint changes.
  • Keep credit availability hints and billing charge inputs aligned with manifest operations and host enforcement. A hint must not become an authorization decision, and a best-effort charge must not block the app action.
  • Keep front-component context, selected-record filters, selected-object metadata, location fields, canonical routes, host actions, inbox permissions, file-field checks, storage namespaces, and renderer bridge types aligned. A valid app bundle can still fail at host execution.
  • Keep renderer build plugins, direct-export unwrapping, shared dependency export maps, worker remote-element output, approved fetch origins, iframe host props, host UI markers, event-source cleanup, outside-press ownership, page-zoom behavior, clone precedence, and style injection aligned. A build or renderer change can lose an event, grant unintended iframe access, or permit an unintended request.

Important failure modes

TriggerConsequenceGuard
An app is vetted but not listedPublic detail access rejects itTreat listing as exposure and vetting as trust
Marketplace role, capability, iframe media, billing, or connect-link data does not match the permission summaryUsers see incomplete or incorrect access before installKeep detail fields, role mappings, object identifiers, media permissions, billing state, link replacement, and summary builders aligned
A first-party app is missing from the shared identifier list used by curation or billing exemptionsThe wrong app is featured or a high-frequency app consumes normal creditsUse one shared universal identifier for catalog and billing rules
Install or upgrade status is not restored after reload or reconnectThe user sees an app change as idle while server work continuesQuery by universal identifier and job ID, then reconcile terminal state
The installed application fragment omits a refreshed extension fieldThe app can install successfully but the client shows stale or incomplete app stateKeep the application query fragment aligned with the installed application contract
A media capability request is granted after cancellation or by a member without app-management permissionThe app receives workspace-wide media access without valid authorizationCheck permission, abort state, and grant result before resolving the request
A selected-record filter is discarded when selected IDs are emptySelect-all actions target no records or the wrong recordsPreserve the host-provided filter in execution context
A front component reads a stale context value after host state changesThe app shows or acts on the wrong object or selectionSubscribe through the SDK context hook and compare the selected value before updating
A related record path skips its second relationApp metadata is rejected before syncRequire each relation before declaring a later path segment
A standalone page layout widget has no target tab or positionThe host cannot place the widget in the app layoutDeclare the tab universal identifier and explicit position
A conditional availability variable is used as a normal runtime valueApp code throws outside an availability expressionUse the variables only in the declaration expression boundary
An external absolute URL is used for an app logo or gallery imageThe asset is ignored and the app may lose its marketplace display imageBundle assets in the app public directory and use relative paths
A workflow contains an unsupported step or cycleThe app workflow cannot be registeredValidate the supported step set and graph shape before export
An agent trigger uses an unknown type, duplicate identifier, or wildcard database eventThe app agent cannot be registeredUse supported model capabilities, UUIDs, event names, and trigger limits
A messaging provider points to an unknown connection or send functionProvider sync or outbound messaging failsPoint references to UUIDs declared in the same app
A validation rule emits an unsupported function or non-finite literalThe host cannot compile the ruleBuild expressions with the SDK helpers and valid finite values
A billing declaration uses an invalid type, amount, or duplicate nameApp validation fails or usage is charged under an unclear nameValidate operation types, positive recurring amounts, labels, and distinct names
A requested iframe media origin is not an exact HTTPS origin or declares no mediaApp declaration validation failsRequire a unique exact HTTPS origin with microphone or camera access
A custom callback has no state or a token response has no access tokenAccount linking fails without a trusted return path or usable credentialRequire signed state and validate the token response
A refresh response omits the refresh tokenThe next refresh loses the only long-lived credentialPreserve the previous refresh token when the provider does not rotate it
A token endpoint returns a client error during refreshThe account needs user authorization againMark the account for reconnect only for token-endpoint client errors; keep 5xx and transport failures transient
A personal connection is replaced by a workspace connection when both existApp logic uses the wrong user's accountSelect the request user's connection before the shared fallback
An attachment upload completes outside the message attachment field or before storage accepts itIngested messages lack a usable attachment or retain an invalid file referenceUse the SDK attachment helper and pass its result to ingestMessages only after upload succeeds
A message redelivery ignores hasAttachmentsThe provider downloads and uploads the same files againTreat the server attachment state as the redelivery guard
An inbox assistant mention is stored as display textThe inbox loses the assistant reference when it renders the messageUse the canonical assistant mention token from the SDK
An inbox archive uses the wrong thread or member setThe wrong members see an open or archived conversationPass the thread identity and intended member identities through the SDK action
AI stream history, sequence catch-up, or event completion is lostAn app shows a partial conversation or cannot resume after a dropped streamKeep history, catch-up chunks, event types, and early-close advice compatible
A logic function enqueues a batch with a mismatched target or unsupported payload sizeSome runs are rejected or cannot be traced to the intended functionUse one declared logic-function identifier and handle the returned job IDs and byte limits
A logic function reads or writes key-value state with the wrong scope or no runtime tokenState is missing or the action stops before reaching the metadata APIUse the intended scope and require the app runtime configuration
A credit availability response is unavailable or malformedThe app may do expensive work without a useful hintTreat availability as a fail-open hint and rely on host billing enforcement
A front component sends an inbox action without the required member or app accessThe message, archive, or thread link is rejectedKeep inbox actions behind the host permission and token boundary
A component requests an unsupported route or page surfaceThe host rejects navigationUse typed canonical routes supported by the host
A worker uses an unapproved origin or missing bridge stateNetwork or host actions fail at the extension boundaryPass approved origins and initialize the host bridge before rendering
A managed iframe receives raw app allow, sandbox, or source propsThe iframe can receive media or embed behavior outside the host decisionNormalize sensitive names and render only the trusted host values
A host UI event is forwarded as a worker event or an outside pressAn app control closes or changes a host menu, dialog, or popoverMark host UI and filter it in event and outside-press forwarding
A zoom gesture inside a portal is treated as page zoomThe browser zooms the whole page while the app control is activeTrack portal geometry and prevent only page-zoom gestures inside remote elements
A wrapped element loses event precedence after cloningA control stops responding or keeps stale listenersPreserve source-aware handlers, cleanup, clone precedence, and refs

Key files

FileWhy to read it
packages/…/marketplace-catalog-sync.service.tsRegistry package to marketplace registration flow
packages/…/marketplace.module.tsMarketplace service boundary and exports
packages/…/marketplace-public.resolver.tsPublic listing and vetting rules
packages/…/marketplace-query.service.tsMarketplace detail and capability data
packages/…/marketplace-app-detail.dto.tsMarketplace detail contract
packages/…/marketplaceAppDetailFragment.tsClient detail contract for install review
packages/…/SettingsApplicationInstallPermissionValidationModal.tsxPermission and trust review before install
packages/…/getMarketplaceAppConnectLink.tsExternal connection-link expansion
packages/…/useInstallMarketplaceApp.tsInstall job tracking and state refresh
packages/…/applicationFragment.tsInstalled application contract for extension state
packages/…/authentication.tsZapier credential and endpoint contract
packages/…/triggers.utils.tsWebhook subscription and record-event mapping
packages/…/crud_record.tsMetadata-driven record actions
packages/…/README.mdSDK and standalone CLI boundary
packages/…/package.jsonPublic SDK entry points, renderer build export, and version boundary
packages/…/CHANGELOG.mdCurrent SDK contract changes and compatibility notes
packages/…/index.tsPublic SDK declaration surface
packages/…/loose-shared-types.type.tsApp-facing manifest type boundary
packages/…/define-connection-provider.tsOAuth, discovery, custom, and API-key provider contract
packages/…/define-messaging-provider.tsMessaging provider declaration boundary
packages/…/rule-expression.tsTyped validation-rule expression boundary
packages/…/define-application.tsApplication identity, variables, billing, and iframe media contract
packages/…/conditional-availability-variables.tsDeclaration-only availability expression surface
packages/…/define-workflow.tsApplication workflow contract
packages/…/define-health-check.tsWorkspace and member health-check contract
packages/…/connection-provider-oauth-flow.service.tsHost OAuth account-linking flow
packages/…/connection-provider-custom.controller.tsCustom provider callback boundary
packages/…/parse-token-response.util.tsToken response and expiry contract
packages/…/app-oauth-refresh-tokens.service.tsOAuth refresh and reconnect error boundary
packages/…/index.tsPublic logic-function runtime services
packages/…/enqueue-jobs.tsBatch logic-function job boundary
packages/…/ingest-messages.tsProvider message ingestion boundary
packages/…/stream-conversation.tsLive conversation stream boundary
packages/…/index.tsPublic front-component and inbox extension surface
packages/…/frontComponentHostCommunicationApi.tsTyped host actions for front components
packages/…/get-front-component-build-plugins.tsPublic front-component build boundary
packages/…/create-shared-dependencies-shim-plugin.tsShared dependency bridge for renderer builds
packages/…/FrontComponentRenderer.tsxIsolated worker and host rendering boundary
packages/…/HostIframeElement.tsxTrusted iframe media boundary
packages/…/wrapEventHandler.tsWorker event serialization and host UI filtering
packages/…/remote-worker.tsWorker communication and fetch policy