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 / external-integrations

External integrations and communications

External integrations connect a workspace to outside accounts, services, and applications. They support account-based synchronization, messages, calendars, email, files, webhooks, installed application behavior, and delivery between a local application project and a remote Twenty workspace.

Connected accounts

Account ownership

A connected account represents an external identity that a workspace can use. The account belongs either to one workspace member or to the workspace. Its scope controls who may use it and which channels or application actions may access it.

Provider support covers Google, Microsoft, direct IMAP, SMTP, and CalDAV connections. Installed applications can add connection providers for their own external services. These providers identify an account, authorize it, and manage its connection lifecycle. Application providers expose either workspace or user scope so an application can state whether a connection is shared or personal.

References: packages/…/connected-account.entity.ts• L25-127 packages/…/connection-provider-connected-account.service.ts• L42-67 packages/…/connection-provider-lifecycle-hook.service.ts• L37-76 packages/…/application-connection-provider.dto.ts• L23-49 packages/…/connection-provider-scope.enum.ts• L5-12

Account authorization

Account authorization is a controlled handoff between the workspace, the provider, and the external service. The system checks the connection provider, workspace, member, and browser session before it starts. A short-lived signed state value binds the callback to the original workspace and account request.

OAuth providers can use PKCE. The state also carries the scope, reconnect target, and safe return location. After the provider returns a code, the system exchanges it for tokens, identifies the external account, and stores the account with encrypted credentials. A custom provider can receive either a browser callback or a server notification callback. An API-key provider follows the same account boundary without an OAuth callback. It verifies the key through the application's account-identification action before it saves the account. See Connected accounts and messaging for the account and provider flow.

OAuth discovery providers can learn the protected resource and authorization server before sign-in. They reuse a stored client when its discovery state is still valid. Otherwise, they use the provider's supported client identification path and store one client for the workspace.

References: packages/…/app-connection-access.service.ts• L17-57 packages/…/connection-provider-authorization-state.service.ts• L34-120 packages/…/connection-provider-oauth-flow.service.ts• L46-99 packages/…/connection-provider-oauth.controller.ts• L77-253 packages/…/connection-provider-custom.controller.ts• L45-137 packages/…/connection-provider-flow-redirect.service.ts• L40-83 packages/…/connection-provider-api-key-flow.service.ts• L33-98 packages/…/discovered-oauth-client.driver.ts• L67-117

Account credentials

The account keeps credentials, scopes, expiry, and authentication state separate from synced workspace data. Access tokens are reused until they approach expiry. Providers that support refresh renew the credentials and save the new token pair before the next external operation.

The system treats a temporary token endpoint or network failure as retryable. A provider rejection that shows an invalid refresh token moves the account toward reconnect instead of being treated as a transient outage. Direct protocol accounts and API-key accounts do not use OAuth token refresh.

References: packages/…/connected-account-refresh-tokens.service.ts• L51-84 packages/…/connected-account-refresh-tokens.service.ts• L145-225 packages/…/app-oauth-refresh-tokens.service.ts• L28-79 packages/…/connection-provider-api-key-flow.service.ts• L65-90

Application account access

Application account access exposes only the connected accounts that the application and the requesting member may use. A workspace-scoped account is available to the workspace. A member-scoped account is visible only to that member when a request has a member context.

The application can filter accounts by provider, member, and scope. The response refreshes usable credentials before it returns them and omits accounts whose provider is no longer available. This keeps application actions separate from a member's personal account access.

References: packages/…/application-connections-list.service.ts• L64-131 packages/…/application-connections-list.service.ts• L194-297

External channels

Message channels

A message channel is the workspace view of a message source on a connected account. It defines the source to sync, visibility, filters, and rules for turning external participants into workspace people or members.

Google, Microsoft, and IMAP channels import email. Email groups provide shared addresses, and application-owned channels can accept messages from an installed application instead of polling a provider. Folder links track where a message appears in the external source. The shared message path keeps external identities stable, avoids duplicate messages, and preserves thread, participant, and attachment links. Attachment content may remain with the provider until a user requests it.

Blocklists, group-email rules, upstream spam checks, and provider errors all affect whether a message enters the workspace. See Connected accounts and messaging for the message lifecycle.

References: packages/…/message-channel.entity.ts• L51-176 packages/…/messaging-save-messages-and-enqueue-contact-creation.service.ts• L75-137 packages/…/messaging-message-folder-association.service.ts• L16-93 packages/…/messaging-message-cleaner.service.ts• L29-141 packages/…/inbound-email-import.service.ts• L115-158

Calendar channels

A calendar channel is the workspace view of a calendar on a connected account. It carries the calendar identity, sync state, visibility, participant rules, and change-notice state.

Google Calendar, Microsoft Calendar, and CalDAV data are mapped to one workspace event model. Stable external identities support updates and removal. Provider-specific sharing rules can link the same meeting from more than one channel without allowing an attendee channel to replace organizer-owned data.

References: packages/…/calendar-channel.entity.ts• L39-134 packages/…/calendar-save-events.service.ts• L36-309 packages/…/resolve-calendar-event-sharing.util.ts• L13-92 packages/…/calendar-event-composer.service.ts• L46-82

Channel visibility

Channel visibility limits how much external data a member can see. Message channels can share full messages, subjects, or only metadata. Calendar channels can share full events or only calendar metadata.

The visibility decision uses the channel associations and the member's ownership of the connected account. Calendar fields such as the title and description are restricted when no associated channel grants full access. The same rule applies to list and single-record views.

References: packages/…/apply-messages-visibility-restrictions.service.ts• L31-182 packages/…/apply-calendar-events-visibility-restrictions.service.ts• L30-133

Synchronization

Sync pipeline

Synchronization turns provider records into workspace records while keeping the provider as the source for external state. Each channel tracks progress so discovery and import can continue in batches.

The common flow is:

  1. A provider notice, schedule, blocklist change, or user action marks a channel for work.
  2. Discovery finds changed external identities and advances the provider cursor.
  3. Import applies channel and workspace rules.
  4. Accepted records are saved with their links to channels, threads, people, members, events, or remote attachments.
  5. The channel records the next sync state or enters recovery.

This diagram shows how an external change becomes workspace data.

flowchart LR
    A[External change] --> B[Channel sync request]
    B --> C[Discover changed identities]
    C --> D[Apply channel rules]
    D --> E[Import workspace records]
    E --> F[Save links and sync state]

Temporary failures wait for retry. Permission failures require account recovery. An invalid message cursor starts a new discovery pass so incremental sync does not silently miss records. A full message pass also removes channel links for records no longer present in the provider result.

References: packages/…/channel-sync.service.ts• L61-184 packages/…/gmail-get-history.service.ts• L15-63 packages/…/messaging-message-list-fetch.service.ts• L118-255 packages/…/messaging-message-cleaner.service.ts• L143-281 packages/…/message-channel-sync-status.service.ts• L59-239

Message synchronization

Message synchronization discovers folders and message identities before it imports message content. Provider history can report additions, deletions, and label changes. Folder links are then reconciled so workspace messages follow the source mailbox.

The import path filters spam, blocked senders, group-email rules, and channel handles before it saves a message. It saves message, thread, participant, folder, and attachment links through the shared message path. External message and header identities prevent duplicate workspace records across repeated syncs. Drafts that become sent are refreshed instead of becoming separate messages, and later matching work can repair links to people or members.

Attachment metadata is stored separately from attachment content. The system ignores mail-system files and inline images that do not represent user files. Eligible remote attachments keep their provider identity and are fetched from Gmail, Microsoft, or IMAP only when needed. This keeps message import light while still allowing the workspace to present the file later. Fetches are limited per connected account so repeated access does not overload the provider. The file service then serves a stored file or opens its remote content through the remote file source, without treating the remote file as local storage.

Message text is normalized without quoted history where the provider body marks a prior exchange. This keeps a new message focused on its current content while preserving the original message record for the thread.

References: packages/…/gmail-get-history.service.ts• L66-120 packages/…/messaging-message-list-fetch.service.ts• L107-255 packages/…/messaging-messages-import.service.ts• L103-227 packages/…/messaging-message.service.ts• L54-381 packages/…/messaging-save-messages-and-enqueue-contact-creation.service.ts• L75-293 packages/…/messaging-message-attachment.service.ts• L106-191 packages/…/messaging-remote-attachment.service.ts• L53-105 packages/…/filter-importable-message-attachments.util.ts• L7-27 packages/…/resolve-message-attachment-mime-type.util.ts• L8-29 packages/…/extract-imap-body-structure-attachments.util.ts• L10-54 packages/…/extract-microsoft-file-attachments.util.ts• L7-29 packages/…/get-attachment-data.util.ts• L9-54 packages/…/file.service.ts• L92-176

Calendar synchronization

Calendar synchronization separates event discovery from event import. Discovery records changed event identities. Import then normalizes provider data and reconciles event fields, channel links, cancellations, recurrence, and participants.

The save path can skip unchanged records and remove events that are canceled or no longer belong to the channel. Creation returns an external identity when possible, so a later sync can reconcile a provider-created event with its workspace record.

References: packages/…/calendar-events-import.service.ts• L51-211 packages/…/calendar-save-events.service.ts• L36-309 packages/…/caldav-create-event.service.ts• L25-115

Messaging and email

Email sending

Email sending uses a send-capable connected account and one of its verified aliases. The send flow supports new messages, replies, drafts, attachments, and sent-message persistence.

After delivery, the system saves the sent message through the shared message path. Provider message and thread identities are used when available. When a provider does not return them, the message header or parent thread keeps the send distinct and keeps replies in the right thread. Attachment storage is best effort, and temporary copies that are not linked to the saved message are removed. A cleanup failure after provider delivery does not claim that the email was unsent because later synchronization can repair local state.

A sent thread can also be linked to a workspace record when the caller has permission to update that record. This link uses the caller's record access and does not bypass it.

References: packages/…/send-email.service.ts• L21-103 packages/…/sent-message-persistence.service.ts• L38-177 packages/…/format-sent-message.util.ts• L13-65 packages/…/resolve-outbound-thread-external-id.util.ts• L5-29 packages/…/sent-message-record-link.service.ts• L19-77 packages/…/sent-message-persistence.service.spec.ts• L74-153

Campaign delivery

Campaign delivery sends a planned message to an audience through a verified workspace domain. A campaign can send now or at a future time. The delivery path recounts the audience near send time and applies suppression and plan rules before it queues recipients.

Campaign records preserve the sender, audience, content, topic, and schedule so the sent view remains useful after related workspace records change.

References: packages/…/message-campaign.service.ts• L1-200 packages/…/message-campaign-lifecycle.service.ts• L1-200 packages/…/message-campaign-audience.service.ts• L1-200 packages/…/email-group-message-outbound.service.ts• L49-153

Inbound email

Inbound email routes a message sent to a configured inbound address into an email-group channel. The route uses the envelope recipient and domain to select the channel, then imports the message through the normal message path.

Known message headers preserve the workspace thread. Unmatched recipients, unconfigured domains, and upstream spam messages do not create workspace messages. The source cleans up the inbound message after import or exclusion.

References: packages/…/inbound-email-import.service.ts• L45-158 packages/…/inbound-email-import.service.ts• L161-233 packages/…/is-upstream-spam.util.ts• L6-21

Email attachments

Email attachments use workspace file storage as a temporary handoff between the composer and the outbound send. The composer validates the file before upload and receives signed access without exposing the storage location.

Temporary files remain until the email flow uses or removes them. Cleanup continues when one file fails so a single stale attachment does not block the rest. Sent-message persistence also keeps the message when an individual attachment upload fails.

References: packages/…/file-email-attachment.service.ts• L23-89 packages/…/EmailComposerFields.tsx• L291-314 packages/…/sent-message-persistence.service.ts• L103-177 packages/…/file.service.ts• L217-276

Suppression controls

Suppression controls stop delivery to addresses that must not receive a message. Campaign and other bulk sends resolve suppression again at final handoff rather than trusting an earlier audience preview.

This last check protects the gap between audience selection and delivery. Unsubscribe topics and suppression records therefore affect the provider handoff, not only the user interface.

References: packages/…/message-suppression.resolver.ts• L46-93 packages/…/unsubscribe-topic.resolver.ts• L38-92 packages/…/emailing-domain-sender.service.ts• L89-209

Workflow communications

Workflows can use connected accounts to send or draft email and create calendar events. A record event, schedule, webhook, or manual run can therefore produce work in an external channel.

The workflow run records the selected account and action result. Application manifests can declare these account references, which are resolved during manifest validation before the workflow becomes workspace state. See Connected accounts and messaging for provider delivery rules.

References: packages/…/send-email.workflow-action.ts• L22-58 packages/…/create-calendar-event.workflow-action.ts• L19-52 packages/…/reconstruct-workflows-manifest.util.ts• L86-119

Webhook communications

Provider notifications

Provider notifications are inbound notices that keep message and calendar channels current. A valid notice schedules channel synchronization. It does not write provider data directly into workspace records.

Subscription state belongs to the channel. The system claims creation work to avoid competing watches, renews watches that are near expiry or stale, and revokes watches when a workspace is suspended or deleted.

References: packages/…/channel-sync.service.ts• L84-183 packages/…/messaging-webhook-subscription.service.ts• L42-368 packages/…/webhook-subscription-renewal.cron.job.ts• L68-140

Workspace event webhooks

Workspace event webhooks send selected workspace changes to an external URL outside the request that changed the workspace. They can match record events and metadata changes. A workspace role controls which records the webhook may include.

Webhook delivery is queued and rate limited before individual requests are sent. The payload describes the matching event in JSON. When configured with a secret, each request carries freshness data and an HMAC signature. Secure HTTP checks reject targets that resolve to private addresses. Delivery records keep the response and outcome for later inspection.

Workspaces can manage webhooks through GraphQL, REST, and application tools. Read, write, and delete operations use separate access policies. For application and extension behavior that uses these events, see Extension integrations.

References: packages/…/webhook.controller.ts• L36-105 packages/…/call-webhook-jobs.job.ts• L37-135 packages/…/create-webhook.tool.ts• L13-84 packages/…/webhook.resolver.ts• L31-89 packages/…/webhook-write-access-policy.constant.ts• L5-21 packages/…/webhook-read-access-policy.constant.ts• L5-18

Installed applications

Application catalog

An application registration is the shared identity for a package or OAuth-only client. It gives the catalog and installed workspaces a stable application identity, version, manifest, display data, and declared access.

The marketplace catalog exposes listed and built-in applications for discovery. Detail data shows the requested capabilities, roles, data objects, media permissions, billing, and support links before installation. This lets a workspace review the application's intended reach before it approves workspace state. See Packaged installed applications for the complete lifecycle.

References: packages/…/application-registration.service.ts• L905-1059 packages/…/marketplace-query.service.ts• L48-120 packages/…/marketplace-query.service.ts• L141-236 packages/…/marketplace-app-detail.dto.ts• L23-155

Application authorization

Application authorization records a member's consent for an application in a workspace. It stores the approved scope and use time, and it can be revoked for one member, one workspace, or one application without affecting unrelated grants.

An external OAuth client can discover an application's public identity and requested scopes before it starts consent. Authorization records the grant before tokens are issued. Revocation and later token use continue to check the client, grant owner, and current workspace access.

References: packages/…/application-authorization.service.ts• L16-57 packages/…/application-authorization.service.ts• L147-204 packages/…/oauth-client.resolver.ts• L35-92

Application installation

Installation turns a registration into workspace-scoped application state. The system checks server compatibility and access approval, stores the package, applies its manifest, and runs the declared lifecycle work.

Install, upgrade, and uninstall operations are serialized per workspace application. A fresh install can roll back partial state. An upgrade keeps the existing application when the new version fails. A package can contribute workspace data, user-interface parts, server actions, permissions, connection providers, messaging providers, workflows, and application variables. Local development applications are synchronized by the CLI, and OAuth-only applications have no code package to install.

Capability and embedded media access are limited to the approved set. Pre-install and post-install actions can prepare or finish workspace behavior. Uninstall removes application-owned workspace state and runtime resources, but it is blocked while another workspace depends on the shared application registration.

References: packages/…/application-install.service.ts• L102-168 packages/…/application-install.service.ts• L376-619 packages/…/application-uninstall-runner.service.ts• L36-117 packages/…/application-sync.service.ts• L340-494

Application manifests

An application manifest is the portable declaration of the workspace behavior and data that an application owns. Manifest synchronization validates references, compares the declaration with workspace state, and applies a migration that creates, updates, or removes the owned parts.

The model covers data objects and fields, views, layouts, navigation, roles, permissions, workflows, agents, skills, connection providers, messaging providers, related record paths, validation rules, and variables. It also maps application health checks and media permission requests to installed application state. Stable universal identifiers connect these parts across source, install, sync, export, and pull.

The sync can produce a dry-run plan before it changes the workspace. Removing a connection provider can also remove the connected accounts that depend on it, so the system validates the migration before it revokes those accounts and tokens. Translation updates and SDK client generation follow the resulting application state.

References: packages/…/application-sync.service.ts• L65-143 packages/…/application-manifest-migration.service.ts• L183-388 packages/…/application-manifest-apply.service.ts• L28-100 packages/…/application-manifest-migration.service.ts• L312-354

Application export

Application export rebuilds a portable manifest from application-owned workspace state. It also reports coverage for records that are exported, derived by the engine, owned by another application, unsupported, or excluded as runtime or workspace state.

Export can include dependency files, declared source files, and public assets. The CLI uses this export to pull a locally developed application. Packaged applications and the standard application are not treated as locally editable exports.

References: packages/…/application-development.service.ts• L104-123 packages/…/fetch-app-export.ts• L79-123 packages/…/fetch-app-export.ts• L174-202

Application configuration

Application variables hold workspace or user configuration for an installed application. Values are encrypted, secret values are masked in display views, and only workspace-scoped values become server environment values for application execution.

Required configuration takes priority over general health state. User variables stay separate from workspace variables and are resolved for the current member. See Extension integrations for the broader application extension model.

References: packages/…/application-variable.service.ts• L35-75 packages/…/application-variable.service.ts• L105-175 packages/…/user-application-variable-value.service.ts• L53-91

Application media permissions

Application media permissions control whether an embedded application may use a member's microphone or camera. The application manifest declares requested permissions for an origin. A workspace administrator reviews those requests and grants only permissions that the installed application requested.

The granted set is exposed separately from the requested set. If the request changes, the workspace must review it again before the new access can be granted.

References: packages/…/application-iframe-media-permission.resolver.ts• L50-113 packages/…/application-iframe-media-permission.service.ts• L31-107 packages/…/iframe-media-permission.input.ts• L5-18 packages/…/application.entity.ts• L141-146

Application health

Application health checks report whether an installed application can operate for a workspace or a member. A health check is an application-owned function that returns a small status and optional title, description, and user action.

The system returns unknown when the check fails or returns an invalid result. A per-member check runs only when the application enables it and is rate limited to protect both the workspace and the application. Configuration remains a separate prerequisite, so missing required settings can take priority over a healthy runtime result.

References: packages/…/application-health-check.service.ts• L20-157 packages/…/user-health-check-rate-limit.constant.ts• L1-2 packages/…/build-user-health-check-rate-limit-key.util.ts• L1-10 packages/…/application-manifest-migration.service.ts• L464-514

Application monitoring

Application monitoring gives an owner a time-bounded view of application runs, errors, rate limits, lifecycle events, versions, function activity, and credit use. An administrator can view the same registration across installed workspaces.

The period is limited by audit-log retention and uses larger time buckets for longer ranges. Ownership, workspace permissions, feature access, and application scope protect the result. Credit data can be unavailable without hiding the rest of the monitoring view.

References: packages/…/application-monitoring.service.ts• L66-121 packages/…/application-monitoring.service.ts• L124-158 packages/…/application-monitoring.service.ts• L161-254

CLI application delivery

Application source build

The application CLI turns local source into a validated manifest and a set of deployable files. It includes code reachable from declared application entries, preserves needed source and asset files, builds server and front-end parts, and records file identities for later synchronization.

The build rejects unsafe or missing local inputs and detects collisions between source files and generated files. This creates one package view that can support local development, remote synchronization, export, and publishing. See CLI application delivery for the developer workflow.

References: packages/…/manifest-build.ts• L95-186 packages/…/manifest-build.ts• L598-831 packages/…/manifest-validate.ts• L265-342 packages/…/build-application.ts• L56-219 packages/…/collect-application-source-files.ts• L12-149

Remote application delivery

Remote delivery sends a local application's manifest and files to one explicit Twenty target. The CLI can create or update the local application record, request a migration plan, show its changes, apply the plan, upload application files, publish a package, and generate a client from the remote API schema.

The plan separates creates, updates, deletes, and dependent deletes. Secret variable values remain hidden. Destructive changes are shown before apply, and missing source entities are pruned only when the selected mode allows it. File delivery uses server-issued upload targets and completes only the files that storage accepts.

This diagram shows the main remote delivery path.

flowchart LR
    A[Local source] --> B[Build and validate manifest]
    B --> C[Select remote target]
    C --> D[Request migration plan]
    D --> E[Review changes]
    E --> F[Upload files]
    F --> G[Apply manifest]
    G --> H[Workspace application state]

Publishing a package registers it in the selected registry. Publishing does not install it in a workspace. Install remains a separate workspace action.

References: packages/…/format-app-plan.ts• L327-402 packages/…/group-app-plan-cascades.ts• L7-43 packages/…/parse-app-plan.ts• L47-77 packages/…/upload-app-files.ts• L322-385 packages/…/publish-app-to-server.ts• L18-143 packages/…/application-development.service.ts• L126-205

Application pull

Application pull brings an export from a remote custom application into a local project. It compares the remote manifest and files with a target-bound pull base, keeps local-only definitions where they are not replaced by workspace state, and writes only the planned changes.

The pull protects identifiers that the export still owns, tracks overwritten local changes, and records fingerprints for later pulls. It can restore declared front-end source, public assets, and dependency files, while rejecting unsupported or unsafe file paths. A report shows incomplete coverage, skipped entities, local-only files, and changes that replaced local edits.

References: packages/…/run-app-pull-command.ts• L42-107 packages/…/run-app-pull-command.ts• L148-246 packages/…/pull-application.ts• L32-227 packages/…/plan-public-asset-writes.ts• L11-68 packages/…/parse-pull-files.ts• L21-113

CLI target access

The CLI resolves a named remote or environment target before it makes a request. A target supplies the API URL and either an OAuth session or an API key. Expiring OAuth sessions can be renewed, and authenticating proxy headers can be loaded for that remote.

Transport keeps requests inside the selected target, does not follow redirects, limits response size, applies a timeout, and reports proxy, network, and authentication failures separately. This protects credentials and makes a failed delivery point to the target that needs attention.

References: packages/…/resolve-target.ts• L22-145 packages/…/create-target-fetch.ts• L116-202 packages/…/resolve-proxy-headers.ts• L1-200

Change checklist

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

  • Keep account scope, application connection permissions, reconnect ownership, encrypted credentials, and channel access aligned.
  • Keep OAuth token response parsing, expiry calculation, refresh timing, token rotation, API-key verification, and reconnect error mapping aligned for built-in and application providers.
  • Keep OAuth state claims, one-time flow secrets, browser-session checks, callback methods, workspace-host redirects, and safe internal return paths aligned.
  • Keep discovered resource metadata, authorization-server metadata, client identification, stored-client reuse, redirect URLs, and discovered scopes aligned.
  • Keep provider normalization, stable external identities, channel roles, visibility rules, folder links, and orphan cleanup aligned across message and calendar sync.
  • Keep discovery cursors, queued identities, import progress, retry state, provider history events, full-sync deletion, and provider notice handling aligned so a channel cannot silently skip or repeat data.
  • Keep attachment metadata filtering, provider identities, remote file origins, lazy content fetch, MIME type fallback, and per-account fetch limits aligned across Gmail, Microsoft, and IMAP.
  • Keep sender aliases, inbound domain routing, campaign suppression, audience recounts, threading headers, outbound fallback identities, and attachment cleanup aligned with provider delivery.
  • Keep sent-thread record links behind the caller's record update permission and preserve the distinction between manual and automatic links.
  • Keep manifest identifiers and references aligned across source build, install, sync, export, workflow account resolution, related record paths, validation rules, and application-owned data.
  • Keep manifest coverage rules separate from runtime configuration, member assignments, workflow versions, health results, media grants, and other state that cannot be exported.
  • Keep application registration versions, capability approval, media permission approval, lifecycle locks, rollback, uninstall blocking, and installed workspace state aligned.
  • Keep requested and granted media permissions tied to the installed application's current manifest and origin.
  • Keep health-check enablement, workspace and member scope, required configuration state, result validation, and per-user rate limits aligned.
  • Keep workspace and user application variables separate, encrypted, masked, and excluded from reserved runtime names.
  • Keep monitoring retention, period buckets, ownership scope, workspace filters, event sources, and credit usage mapping aligned.
  • Keep webhook event matching, role-based record access, signing, target safety checks, queue retry, and rate limits aligned across GraphQL, REST, tools, and delivery jobs.
  • Keep manifest validation, build outputs, file checksums, upload targets, destructive plan handling, remote selection, pull bases, public-asset paths, and generated clients aligned across CLI and server delivery.
  • Keep package publishing separate from workspace installation, and preserve the distinction between local development apps, packaged apps, and OAuth-only clients.

Important failure modes

TriggerConsequenceGuard
An application provider returns an invalid refresh tokenIts connected account cannot access the external serviceTreat provider 4xx token failures as reconnect state and keep transport or 5xx failures retryable
An API key is empty or account identification failsThe application cannot create a usable connected accountTrim and verify the key through the provider's identification action before saving it
OAuth callback state is missing, expired, consumed, or does not match the requestThe account flow cannot complete or may be attached to the wrong workspaceRequire signed state, one-time flow secrets, browser identity checks, and binding to the provider, workspace, member, and reconnect target
A custom callback omits the state query parameterThe provider cannot complete the account flowReject both browser and notification callbacks before forwarding the request
A discovered OAuth resource names another protected resourceAuthorization can target an unintended serviceCheck that discovered resource metadata matches the configured resource
A reconnect identifies a different external accountExisting channel data can be attached to the wrong identityCompare the identified external account before updating the reconnect target
A provider cursor becomes invalidIncremental sync can miss external recordsReset discovery and run a full list pass
A full message sync does not remove associations absent from the provider resultDeleted or moved external messages remain visible in the channelDiff the full provider result against channel associations and clean orphan messages and threads
A remote attachment is saved with an unsupported or system-only file identityThe workspace stores a file that is not useful to a memberFilter mail-system files and inline images before creating remote file records
A provider attachment is missing or the connected account exceeds its fetch limitA message attachment cannot be read at that timeResolve content through the message association and provider identity, return not-found cleanly, and rate limit each account
A calendar sharing key uses the wrong provider identityOne meeting can duplicate or merge with an unrelated meetingUse provider-specific sharing keys and channel roles
Suppression is checked only during audience selectionA newly unsubscribed person can receive a campaignResolve suppression again at final delivery handoff
A provider accepts an email but local persistence failsThe email is delivered while local state remains staleTreat post-send persistence as recoverable and let later sync reconcile it
A provider omits message or thread identities and the send uses one shared empty keyUnrelated sent emails can collide or a reply can leave its threadFall back to the message header for new sends and the parent thread for replies
An attachment upload fails during sent-message persistenceThe message can be lost or one failed file can block delivery stateUpload files independently, save the message with successful files, and remove unclaimed temporary copies
An inbound recipient does not match a configured email-group channelThe inbound message is not importedMatch the envelope recipient to the configured domain and channel handle before saving
A webhook target resolves to a private addressAn outbound request can reach an internal serviceApply secure HTTP target checks before delivery
A webhook role cannot access the changed recordThe external system receives an event that the webhook should not exposeApply the webhook role's record access gate before queueing delivery
Webhook events exceed the workspace delivery limitSome matching events are not sent immediatelyAdmit events through the webhook rate limiter before creating delivery jobs
An application manifest references an unavailable record, account, or owned logic functionInstall, sync, or export cannot produce valid workspace stateValidate stable references during manifest build, sync, and export
A manifest removes a connection provider with active accountsThose accounts must be disconnected before metadata removal can completePlan account deletion and token revocation before applying the final migration
An application requests media access that is not in the installed manifestThe requested access can no longer be trusted as approvedIntersect approval with current requested permissions and require review when requests change
An application health check fails or returns an invalid resultThe application may appear unavailable even when the failure is temporaryReport unknown health and keep per-user checks rate limited
An application update adds access without approvalA package can gain access without workspace intentCompare requested capabilities and media permissions with granted permissions before activation
An owner uninstalls an application that serves another workspaceOther installations can lose a required server routeBlock owner uninstall while dependent installations remain
A local source file is outside the project, missing, or collides with a built fileThe package can contain unsafe or incomplete application contentRestrict collected files to the project, reject missing imports, and detect output collisions
A server returns an invalid plan or an upload target for an unknown fileThe CLI can apply the wrong workspace change or lose a fileValidate the application identifier, action shape, file paths, and upload response before apply
A destructive change is hidden inside a cascadeApproval can omit a data-dropping deletionKeep destructive roots visible and report dependent deletes with the root action
A pull receives an unsafe asset path or unsupported file folderLocal files can be overwritten outside the project or the pull cannot be trustedAllow only declared source, dependency, and safe asset paths and reject duplicates
A package is published and the caller assumes it is installedThe registry has a package but the workspace has no application stateKeep publish and workspace installation as separate actions
The CLI follows a redirect or sends proxy credentials to another hostCredentials can reach an unintended serviceBind requests to the selected target and handle redirects without following them
A local environment is downgradedDatabase state can be newer than the running imageBlock downgrades and use an upgrade that preserves data volumes

Key files

FileWhy to read it
packages/…/connected-account.entity.tsDefines external account scope, state, credentials, and channel links.
packages/…/connection-provider-oauth-flow.service.tsShows the application-provider authorization boundary.
packages/…/connection-provider-authorization-state.service.tsShows signed callback state and one-time flow-secret handling.
packages/…/connection-provider-oauth.controller.tsShows browser checks, OAuth callbacks, and workspace redirects.
packages/…/connection-provider-custom.controller.tsShows custom provider browser and notification callbacks.
packages/…/discovered-oauth-client.driver.tsShows OAuth resource discovery and stored-client reuse.
packages/…/connection-provider-api-key-flow.service.tsShows API-key account verification and persistence.
packages/…/connected-account-refresh-tokens.service.tsShows token reuse, refresh, encryption, and provider error handling.
packages/…/application-connections-list.service.tsShows application account scope, privacy, refresh, and credential access.
packages/…/message-channel.entity.tsDefines message-source scope, filtering, visibility, and sync state.
packages/…/calendar-channel.entity.tsDefines calendar-source scope, visibility, and sync state.
packages/…/channel-sync.service.tsConnects account and provider notices to channel sync.
packages/…/messaging-message-list-fetch.service.tsShows message discovery, cursor progress, full-sync cleanup, and import scheduling.
packages/…/messaging-messages-import.service.tsShows message filtering, folder mapping, batch import, and retry state.
packages/…/messaging-message.service.tsShows idempotent message, thread, draft, and channel-association reconciliation.
packages/…/messaging-save-messages-and-enqueue-contact-creation.service.tsShows the shared save path for participants, folders, attachments, and contact creation.
packages/…/messaging-message-attachment.service.tsShows attachment filtering, remote file records, and attachment links.
packages/…/messaging-remote-attachment.service.tsShows provider-backed attachment retrieval and connected-account fetch limits.
packages/…/file.service.tsShows the boundary between stored files and provider-backed remote file content.
packages/…/inbound-email-import.service.tsShows inbound address routing, thread matching, filtering, and cleanup.
packages/…/messaging-message-cleaner.service.tsShows removal of stale channel links and orphan messages and threads.
packages/…/send-email.service.tsShows provider send, draft actions, and recoverable sent-message persistence.
packages/…/sent-message-persistence.service.tsShows sent-message attachment handling and reuse of the import save path.
packages/…/sent-message-record-link.service.tsShows permission-gated links from sent threads to workspace records.
packages/…/call-webhook.job.tsShows role-filtered event admission and queued webhook delivery.
packages/…/webhook.controller.tsShows REST management and access boundaries for webhooks.
packages/…/marketplace-query.service.tsShows marketplace discovery and the access details shown before installation.
packages/…/application-authorization.service.tsShows workspace and member application consent and revocation.
packages/…/application-install.service.tsShows package installation, approval, rollback, lifecycle hooks, and workspace state.
packages/…/application-uninstall-runner.service.tsShows uninstall dependency checks and lifecycle reporting.
packages/…/application-sync.service.tsShows how a manifest becomes workspace application state.
packages/…/application-manifest-migration.service.tsShows manifest references, workflows, validation, and account cleanup.
packages/…/application-manifest-apply.service.tsShows the shared apply path for installs, upgrades, and CLI development sync.
packages/…/application-development.service.tsShows local application creation, export, manifest sync, and file delivery.
packages/…/manifest-build.tsShows how application source becomes a validated manifest.
packages/…/manifest-validate.tsShows cross-reference, identifier, relation, and layout checks.
packages/…/build-application.tsShows how application code and assets become deployable files.
packages/…/format-app-plan.tsShows plan review, secret masking, cascades, and destructive warnings.
packages/…/upload-app-files.tsShows server-issued file upload and completion.
packages/…/publish-app-to-server.tsShows package registration and the boundary between publishing and installation.
packages/…/run-app-pull-command.tsShows remote export, local reconciliation, and pull reporting.
packages/…/pull-application.tsShows pull planning, protected entities, fingerprints, and writes.
packages/…/resolve-target.tsShows explicit remote selection and credential recovery.
packages/…/create-target-fetch.tsShows target-bound requests, proxy handling, limits, and transport errors.