Loading...
return (
{/* Section 1: Connected accounts */}
{integration.name}
))}
)
}
```
Once an integration is connected, it moves from "Available Integrations" to "Your Connections" automatically.
See the [Playground](https://github.com/membranehq/playground) for a full working example with styling and additional features.
### Hooks reference
| Hook | Returns |
| - | - |
| `useIntegrations()` | `{ items: Integration[], loading, error }` — all integrations in your workspace |
| `useConnections()` | `{ items: Connection[], loading, error }` — current tenant's connections |
| `useMembrane()` | The `MembraneClient` instance for imperative operations |
Pass `{ search: query }` to `useIntegrations` to add search filtering.
## JavaScript SDK
For non-React apps, use the JavaScript SDK directly.
```bash theme={null}
npm install @membranehq/sdk
```
```javascript theme={null}
import { MembraneClient } from '@membranehq/sdk'
const membrane = new MembraneClient({
fetchToken: async () => {
const response = await fetch('/api/membrane-token')
const { token } = await response.json()
return token
},
})
// List available integrations
const integrations = await membrane.integrations.find()
// List current tenant's connections
const connections = await membrane.connections.find()
// Connect to an app (opens popup)
await membrane.ui.connect({ integrationKey: 'hubspot' })
// Reconnect a disconnected connection
await membrane.ui.connect({ connectionId: 'con_abc123' })
// Disconnect
await membrane.connection('con_abc123').archive()
```
## REST API
For any language or framework, use the REST API directly.
**List integrations:**
```
GET https://api.getmembrane.com/integrations
Authorization: Bearer {TOKEN}
```
**List connections:**
```
GET https://api.getmembrane.com/connections
Authorization: Bearer {TOKEN}
```
**Connection UI:** Redirect your user to Membrane's hosted connection page:
```
https://ui.getmembrane.com/embed/integrations/{INTEGRATION_KEY}/connect?token={TOKEN}
```
Optional parameters: `redirectUri` (where to send the user after connecting), `allowMultipleConnections=1`, `name` (pre-set connection name).
**Reconnect:** Redirect to:
```
https://ui.getmembrane.com/embed/connections/{CONNECTION_ID}/refresh?token={TOKEN}
```
See the full [API Reference](/reference) for all available endpoints.
## Advanced
* [Embedded UI](/docs/ways-to-use-membrane/embedded-ui) — customize the connection flow, support multiple connections per app
* [Custom Connection UI](/docs/ways-to-use-membrane/embedded-ui/connection-ui/custom-connection-ui) — build a fully custom connection experience
* [Connection Lifecycle](/docs/how-membrane-works/connections) — auto-refresh, reconnection, webhooks
# Quickstart: AI Agents
Source: https://docs.getmembrane.com/docs/getting-started/quickstart-agent
Connect your AI agent to Membrane and give it the ability to interact with any external app — connect accounts, run actions, read data, and subscribe to events.
Pick the option that matches your agent:
| Your agent | Use |
| - | - |
| Coding agent with CLI access (Claude Code, Cursor, Windsurf, Codex) | [Agent Skills](#agent-skills) |
| MCP-compatible agent (Claude Desktop, ChatGPT, etc.) | [MCP Server](#mcp-server) |
| Custom agent or in-app AI assistant | [Custom / In-app Agent](#custom--in-app-agent) |
## Agent Skills
If your agent supports skills and you can run commands in the terminal, this is the fastest path.
```bash theme={null}
npx skills add membranehq/agent-skills --skill integrate-anything
```
This gives your agent Membrane's integration tools. It sets up the MCP server and credentials automatically. Prompt your agent:
> "Connect to HubSpot and create an action that syncs new contacts to our database."
See [Agent Skills](/docs/ways-to-use-membrane/agent-skills) for details.
## MCP Server
If your agent supports MCP but not skills, add Membrane's hosted MCP server:
```json theme={null}
{
"mcpServers": {
"membrane": {
"type": "url",
"url": "https://api.getmembrane.com/mcp/integrate-anything"
}
}
}
```
The hosted server handles authentication via OAuth — your agent will prompt you to log in when it first connects.
See [MCP Server](/docs/ways-to-use-membrane/mcp) for platform-specific config file locations (Claude Desktop, Cursor, etc.).
## Custom / In-app Agent
If you're building your own agent or embedding an AI assistant in your product:
* **Custom standalone agent** — see the [agent-skills repository](https://github.com/membranehq/agent-skills) for ready-to-run examples with OpenAI SDK, Vercel AI SDK, LangChain, and OpenCode adapters.
* **In-app AI assistant** (multi-tenant, acts on behalf of each user) — see [In-app AI Agent](/docs/getting-started/product-integrations/in-app-ai-agent) for the complete guide with per-user authentication and scoped connections.
# Actions
Source: https://docs.getmembrane.com/docs/how-membrane-works/actions
An action is a single operation your agent or app performs in an external app: create a contact, send a message, list invoices, update a deal. Actions are the primary way to interact with connected apps through Membrane.
## Running actions
Running an action means calling **`/act`** — Membrane's unified entry point for operating on an external app through a connection. One endpoint, one shape, multiple surfaces:
| Way to Use | How to Run |
| - | - |
| CLI | `membrane act --connectionKey Your Connections
{connections?.length === 0 &&No connections yet.
} {connections?.map((connection) => (
{connection.name}
{connection.disconnected ? (
) : (
)}
))}
{/* Section 2: Available apps to connect */}
Available Integrations
{availableIntegrations?.map((integration) => (Whenever you provide `credentials` or `fetchCredentials`, the SDK will associate them with the current user and use them to authenticate requests going forward. You can also update credentials for the current user at any time via SDK or API: ```javascript theme={null} await membrane.self.patch({ credentials: newCredentials }) ```
### Refreshing Credentials If you use OAuth2 authentication type, Membrane will automatically refresh credentials when HTTP 401 response code is received. It will follow the standard OAuth2 token refresh flow: [Refreshing Access Token](https://www.oauth.com/oauth2-servers/access-tokens/refreshing-access-tokens/). # Membrane Universe Source: https://docs.getmembrane.com/docs/how-membrane-works/membrane-universe Membrane Universe is a comprehensive knowledge base about integrations, containing information about external apps, how to connect to them, and pre-built integration logic for common use cases. ## What It Contains Membrane Universe maintains records of: * **External Apps**: Catalog of applications that can be integrated, including their APIs, authentication methods, and capabilities * **Connectors**: Pre-built authentication and API access configurations for connecting to external apps * **Actions**: Ready-to-use actions / tools for popular apps and common use cases. ## AI-Maintained, Human-Curated Membrane Universe is maintained by AI and curated by the Membrane team. This approach ensures: * **Continuous Updates**: New apps and API changes are automatically tracked and incorporated * **Quality Assurance**: Human experts review and validate integration packages * **Community Contributions**: Users can contribute improvements and new integrations ## How It Works When you use Membrane, you automatically benefit from Membrane Universe: * Membrane Agent uses this knowledge base to research external apps and build integrations * Pre-built connectors let you connect to popular apps without writing authentication code * Integration packages provide starting points for common use cases You can browse available integrations in the [Membrane Console](https://console.getmembrane.com) or use the API to query available apps, connectors, and packages. # Tenants Source: https://docs.getmembrane.com/docs/how-membrane-works/tenants Tenants represent the people, teams, organizations, apps, or agents that use integrations in your workspace. They are the primary unit of isolation — each tenant gets their own connections, element customizations, and activity logs. ## How Tenants Work Workspace elements exist at two levels: **Workspace level.** Elements defined at the workspace level serve as shared templates available to all tenants. Tenants can read these but cannot modify them. **Tenant level.** Each tenant can have their own elements and customizations of workspace-level elements — for example, a workspace-level action may have tenant-specific configuration or parameters. Some elements are always workspace-level — for example, integrations are configured once for the whole workspace. Others are always tenant-level — connections, event subscriptions, and activity logs always belong to a specific tenant. Many elements, such as actions, flows, field mappings, data sources, and connectors, can exist at both levels — defined as workspace-wide templates with optional tenant-level customizations. ## Data Visibility Tenants operate under strict data isolation: * **Own data**: Tenants can read and modify their own connections, customizations, and activity logs. * **Workspace data**: Tenants can read workspace-level elements but cannot modify them. * **Membrane Universe**: Tenants can read public connectors, external apps, actions, and other elements from the Membrane Universe but cannot modify them. * **Other tenants**: Tenants can never see or access another tenant's data. This is enforced at the database level. ## Rate Limits You can configure per-tenant rate limits in your workspace settings to control how many resources each tenant can consume (e.g., AI credits per rolling 30-day window). Workspace-level rate limits are shared across all tenants. For full environment isolation (separate configurations, connectors, etc.), use separate workspaces instead. ## Creating Tenants Tenants are created automatically when someone authenticates with a new `tenantKey` in their JWT token (see [Authentication](/docs/how-membrane-works/authentication)). You can also create and manage them via the API — see [Tenants API Reference](/api-reference/customers/create-a-new-customer). ## How Tenant Scoping Works When you generate a JWT token with a tenant's `id` and use it to initialize the SDK or call the API, **all operations are automatically scoped to that tenant**. You don't need to pass a `tenantId` to every API call — the token handles it: ```typescript theme={null} import jwt from 'jsonwebtoken' import { MembraneClient } from '@membranehq/sdk' // Generate a token scoped to a specific tenant const token = jwt.sign( { workspaceKey: process.env.MEMBRANE_WORKSPACE_KEY, tenantKey: 'customer-123', name: 'Acme Corp' }, process.env.MEMBRANE_WORKSPACE_SECRET, { expiresIn: 7200, algorithm: 'HS512' }, ) // Initialize the SDK with this token — all calls are scoped to customer-123 const membrane = new MembraneClient({ token }) // This returns only customer-123's connections const connections = await membrane.connections.find() // This runs against customer-123's connected app const result = await membrane.action('list-deals').run() ``` This is the foundation for building multi-tenant product integrations. Each customer's connections, data, and activity are fully isolated through the token. ## Recommended Uses **One tenant per end-user or organization.** The most common pattern — each customer of your product is a separate tenant with their own OAuth connections, data imports, and integration history. **One tenant per connected app.** If a single user connects multiple instances of the same app (e.g., two Salesforce orgs), you can model each as a separate tenant to keep their connections and data fully isolated. **One tenant per agent.** AI agents that interact with external apps can each be a separate tenant, giving each agent its own set of credentials and activity trail. ## Tenants and Connections Every connection belongs to exactly one tenant. When a tenant authenticates and connects an external app, the resulting connection (with its OAuth tokens or API credentials) is scoped to that tenant alone. If a tenant is archived, all their connections are automatically deactivated. ## Activity Tracking All activity logs are tagged with the tenant ID. Workspace managers can filter logs by tenant in the Console or via the API. Tenants accessing logs through their own token will only see their own activity. # Import and Export Source: https://docs.getmembrane.com/docs/managing-membrane/import-and-export Membrane provides several ways to transfer workspace elements (integrations, actions, flows, field mappings, data sources, data links, and custom connectors) between workspaces. This is commonly used to move configurations from development to production. ## What Gets Transferred **Transferred:** * Integration configurations (which connectors are used) * Actions, flows, and field mappings * Data sources and data links * Custom connector source code * Element structure and relationships **NOT transferred:** * Integration parameters (clientId and secrets, OAuth configurations) * Workspace settings * Internal API definitions * Connection credentials ## Console UI The Console provides a visual interface for importing and exporting workspace elements: 1. Navigate to **Settings > Import/Export** in your workspace 2. **To Export**: Click the export button to download all workspace elements as a zip file 3. **To Import**: Upload the zip file to your target workspace using the import feature This method is ideal for one-time transfers or manual migrations between workspaces. ## API For programmatic or automated transfers, use the Membrane API: **Export workspace elements:** ```bash theme={null} curl -X GET "https://api.getmembrane.com/workspaces/export" \ -H "Authorization: Bearer YOUR_API_KEY" \ --output workspace-export.zip ``` See the [Export Workspace API Reference](/reference/management-api/workspace-migration/export-workspace) for details. **Import workspace elements:** ```bash theme={null} curl -X POST "https://api.getmembrane.com/workspaces/import" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@workspace-export.zip" ``` See the [Import Workspace API Reference](/reference/management-api/workspace-migration/import-workspace) for details. This method is ideal for CI/CD pipelines, automated deployments, or custom tooling. ## CLI [Membrane CLI](https://www.npmjs.com/package/@membranehq/cli) lets you pull and push workspace elements as YAML files, making it possible to version-control your integration configurations and use standard development workflows. ```shell theme={null} npm install -g @membranehq/cli # Pull workspace elements to local files membrane pull # Push local changes to workspace membrane push ``` See the [Membrane CLI npm page](https://www.npmjs.com/package/@membranehq/cli) for full documentation on installation, configuration, and usage. This method is ideal for local development, version control, and diff tracking. ## Comparison | Method | Best For | Pros | Cons | | - | - | - | - | | **Console UI** | One-time transfers, non-technical users | No setup required, visual interface | Manual process | | **API** | Automation, CI/CD pipelines | Scriptable, integrates with existing tools | Requires API authentication setup | | **CLI** | Local development, version control | Full local workspace sync, diff tracking, IDE integration | Requires CLI installation | # Limits Source: https://docs.getmembrane.com/docs/managing-membrane/limits To ensure fair use of our cloud resources, we have implemented a number of limits. If you use a self-hosted version of Membrane, you can change any of these limits by providing corresponding environment variables. **Note:** All limits are applied on a *rolling window basis*, meaning usage is continuously measured over time rather than resetting at fixed intervals. ## API | | Limit | | - | - | | Maximum request size | 10 Mb | | Maximum response size | 30 Mb | | Maximum request duration | 60 seconds | * If you need to work with larger data, please check [Files](/docs/how-membrane-works/binary-data-and-files). * If you need to run longer requests, use [Flows](/reference/workspace-elements/flows). ## Flow Runs | | Limit | | - | - | | Maximum flow run duration | 50 min | | Maximum memory size | 2 GB | | Maximum flow node output | 20 MB | | Maximum parallel flow runs per connection | 1 | | Maximum flow run queue size per connection | 10,000 | ### Understanding flow run queue limits The **flow run queue size per connection** limit controls how many flow runs can be queued for a single connection before new flow runs are rejected with a rate limit error. **Important architectural consideration:** Simply increasing the queue size limit does not solve throughput issues. If your queue is consistently reaching the limit, it means flow runs are being queued faster than they can be processed. Increasing the queue size will only postpone the problem, not resolve it. **To address high-volume flow processing:** * Increase **parallel flow runs per connection** to process flows faster. * Optimize flow logic to reduce execution time. The queue size limit exists to prevent memory issues and provide early feedback when your system cannot keep up with the incoming load. ## External Event Pulls | | Limit | | - | - | | Maximum parallel incremental pulls per connection | 1 | | Maximum parallel "full sync" pulls per connection | 1 | | Maximum parallel pulls per workspace | 10 | | Minimal interval for incremental pull | 60 seconds | | Minimal interval for "full sync" pull | 60 minutes | ## Action | | Limit | | - | - | | Maximum memory when running custom code | 512 MB | | Maximum duration in synchronous mode | 50 seconds | | Maximum duration in asynchronous mode (flow) | 50 minutes | # Monitoring and Troubleshooting Source: https://docs.getmembrane.com/docs/managing-membrane/monitoring-troubleshooting After you implemented the integrations, you need to make sure they are working as expected. When they don't, you need to understand what is happening and why. ## Logging Membrane keeps and provides you with detailed logs of what is happening in your integrations: * [API Requests](/docs/managing-membrane/monitoring-troubleshooting/logs/api-requests) * [External Webhooks](/docs/managing-membrane/monitoring-troubleshooting/logs/external-webhooks) * [External Event Pulls](/docs/managing-membrane/monitoring-troubleshooting/logs/external-event-pulls) * [External Events](/docs/managing-membrane/monitoring-troubleshooting/logs/external-events) * [Internal Events](/docs/managing-membrane/monitoring-troubleshooting/logs/internal-events) * [Flow Runs](/docs/managing-membrane/monitoring-troubleshooting/logs/flow-runs) ## Webhook Notifications To get notified when an important event happens in your integration workspace, you can subscribe to webhook notifications. Learn more about webhook notifications here: [Webhook Notifications](/docs/managing-membrane/monitoring-troubleshooting/webhook-notifications) ## Troubleshooting There are usually three types of problems with integrations: * Integration ran but resulted in an error. * Integration ran but didn't do what you expected it to do. * Integration did not run when you expected it to. Let's look at how to troubleshoot each of these problems. ### Errors When integration errored, follow red dots to find the reason:
#### 1. API Mode Main backend service handling incoming traffic and processing HTTP requests. **Mode-specific Environment Variables:** | Variable | Example | Description | | :- | :- | :- | | `IS_API` | 1 | Enables API mode | | `HEADERS_TIMEOUT_MS` | 61000 | Maximum time to receive request headers | | `KEEPALIVE_TIMEOUT_MS` | 61000 | Maximum time to keep idle connections alive |
#### 2. Instant Tasks Worker Mode Designed for executing semi-instant asynchronous tasks. This mode should be scaled to prevent task queuing. Each worker processes one background job at a time. **Mode-specific Environment Variables:** | Variable | Example | Description | | :- | :- | :- | | `IS_INSTANT_TASKS_WORKER` | 1 | Enables instant tasks worker mode |
#### 3. Queued Tasks Worker Mode Handles long-running tasks such as flow runs, event pulls, and external events. Each worker processes one background job at a time. When limits are enabled, tasks are queued and executed to ensure fair resource distribution among tenants. **Mode-specific Environment Variables:** | Variable | Example | Description | | :- | :- | :- | | `IS_QUEUED_TASKS_WORKER` | 1 | Enables queued tasks worker mode | | `MAX_QUEUED_TASKS_MEMORY_MB` | 1024 | Memory limit for task execution (default: `1024`) | | `MAX_QUEUED_TASKS_PROCESS_TIME_SECONDS` | 3000 | Time limit for task execution (default: `3000`) |
#### 4. Orchestrator Mode Manages schedule triggers, handles data source syncs, and performs cleanup tasks. **Mode-specific Environment Variables:** | Variable | Example | Description | | :- | :- | :- | | `IS_ORCHESTRATOR` | 1 | Enables orchestrator mode | All services scale horizontally without additional configuration (aside from load balancing for API services).
**Common Environment Variables** The following variables are required for all operation modes:
| Variable | Description | Example |
|---|---|---|
| `NODE_ENV` | Environment mode | production |
| `BASE_URI` | Service deployment URL | [https://api.yourdomain.com](https://api.yourdomain.com) |
| `BASE_WEBHOOKS_URI` | Optional: Override webhook endpoint base URL. Use this when you need webhooks to be accessible at a different URL than the main API (e.g., when the API is private but webhooks need a public proxy). Works the same way as BASE\_URI, but only for webhook endpoints. | [https://webhooks-proxy.yourdomain.com](https://webhooks-proxy.yourdomain.com) |
| `BASE_OAUTH_CALLBACK_URI` | Optional: Override OAuth callback endpoint base URL. Use this when you need OAuth callbacks to be accessible at a different URL than the main API (e.g., when the API is private but OAuth callbacks need a public proxy). Works the same way as BASE\_URI, but only for OAuth callback endpoints. | [https://oauth-proxy.yourdomain.com](https://oauth-proxy.yourdomain.com) |
| `BASE_URI_INTERNAL` | Internal service deployment URI (to be used for call from workers to the service) | [https://api.yourdomain.com](https://api.yourdomain.com) |
| `CUSTOM_CODE_RUNNER_URI` | Custom Code Runner service URL | [https://custom-code-runner.yourdomain.com](https://custom-code-runner.yourdomain.com) |
| Authentication variables | Provider-specific API authentication variables. See Authentication section. | `AUTH_PROVIDER`, `AUTH0_*`, `AUTH_SECRET`, `BETTERAUTH_*` |
| `TMP_STORAGE_BUCKET` | Temporary storage bucket (recommend auto-expiration policy) | integration-app-tmp |
| `CONNECTORS_STORAGE_BUCKET` | Connectors storage bucket | integration-app-connectors |
| `STATIC_STORAGE_BUCKET` | Static files storage bucket | integration-app-static |
| `BASE_STATIC_URI` | Static content base URL (files uploaded to the static bucket should be served from this URL) | [https://static.yourdomain.com](https://static.yourdomain.com) |
| `REDIS_URI` or `REDIS_CLUSTER_URI_X` | URL for Redis server. For Redis cluster, provide multiple: REDIS\_CLUSTER\_URI\_1, REDIS\_CLUSTER\_URI\_2, ... | redis\://user:[password@redis-service.com](mailto:password@redis-service.com):6379/ |
| `WORKER_REDIS_URI` or `WORKER_REDIS_CLUSTER_URI_X` | Optional. URL for a dedicated Redis server for background worker tasks. This allows you to separate worker task execution from main Redis operations for better performance and isolation. If not provided, the main Redis server will be used for both purposes. For Redis clusters, provide multiple: WORKER\_REDIS\_CLUSTER\_URI\_1, WORKER\_REDIS\_CLUSTER\_URI\_2, etc. | redis\://user:[password@redis-service.com](mailto:password@redis-service.com):6379/ |
| `SECRET` | JWT token signing secret | s3cr3tString |
| `ENCRYPTION_SECRET` | Credentials encryption secret | v3rys3cr3tstring |
| `MONGO_URI` | MongoDB connection string | mongodb+srv://login:[pass@mymongo.com](mailto:pass@mymongo.com)/integration-api |
| `PORT` | Container listening port (default: 5000) | 5000 |
| `AWS_REGION` | AWS S3 region (when using S3 storage) | eu-central-1 |
| `AWS_ACCESS_KEY_ID` | AWS S3 access key (when using S3 storage) | |
| `AWS_SECRET_ACCESS_KEY` | AWS S3 secret key (when using S3 storage) | |
| `STORAGE_PROVIDER` | Storage provider type: `s3` (AWS S3), `abs` (Azure Blob Storage), or `gcs` (Google Cloud Storage). Default: `s3` | abs |
| `AZURE_STORAGE_CONNECTION_STRING` | Azure Blob Storage connection string (when using Azure storage) | |
| `AZURE_STORAGE_ACCOUNT_NAME` | Azure storage account name (alternative to connection string) | |
| `AZURE_STORAGE_ACCOUNT_KEY` | Azure storage account key (alternative to connection string) | |
| `GOOGLE_CLOUD_PROJECT_ID` | Google Cloud project ID (when using GCS storage) | |
| `GOOGLE_CLOUD_KEYFILE` | Path to Google Cloud service account key file (optional, uses Application Default Credentials if not provided) | |
| `ENABLE_LIMITS` | Optional: Enable workspace resource limits | true |
| `CONNECTION_CREDENTIALS_STORAGE_TYPE` | Optional: storage type for connection credentials: `database`, `external_api`. Default: `database` | |
| `CONNECTION_CREDENTIALS_EXTERNAL_API_ENDPOINT_URL` | When `external_api` chosen for connection credentials storage, this is required. | [https://api.yourdomain.com](https://api.yourdomain.com) |
| `MAX_NODE_RUN_OUTPUT_SIZE_MB` | Optional: Maximum size in megabytes for node run outputs. Default: `20` | 50 |
| `MONGO_MAX_IDLE_TIME_MS` | Maximum time that a connection can remain idle in the pool before being closed. Default: 0 (connections never timeout) | 300000 |
| `MONGO_MIN_POOL_SIZE` | Minimum number of connections to maintain in the MongoDB connection pool. Default: 0 (no minimum) | 3 |
| `MONGO_MAX_POOL_SIZE` | Maximum number of connections allowed in the MongoDB connection pool. Default: 100 | 100 |
| `MONGO_SERVER_SELECTION_TIMEOUT_MS` | Maximum time in milliseconds to wait for MongoDB server selection. Useful in containerized environments with slower DNS resolution. Default: 30000 (MongoDB default) | 60000 |
| `REDIS_CONNECT_TIMEOUT_MS` | Maximum time in milliseconds to wait for Redis connection. Default: 10000 (standalone), 60000 (cluster) | 60000 |
| `REDIS_DISABLE_TLS_VERIFICATION` | Set to `true` to disable TLS certificate verification for Redis connections. Required for AWS ElastiCache with in-transit encryption. | true |
| `SKIP_HEALTH_CHECKS` | Skip specific health checks during startup. Use `all` to skip all checks, or a comma-separated list of: `mongo`, `redis`, `storage`, `custom_code`. Useful for Kubernetes environments with slower initial DNS resolution. | all |
| `HEALTH_CHECK_RETRIES` | Number of retry attempts for health checks after initial failure. Health checks use exponential backoff with jitter between retries. Default: 3 | 5 |
| `HEALTH_CHECK_RETRY_DELAY_MS` | Initial delay between health check retries in milliseconds. Subsequent retries use exponential backoff (delay doubles each retry). Default: 1000 | 2000 |
| `HEALTH_CHECK_MAX_RETRY_DELAY_MS` | Maximum delay between health check retries in milliseconds. Prevents exponential backoff from growing too large. Default: 10000 | 30000 |
| `SELF_HOSTING_TOKEN` | **Required for self-hosted deployments.** Token for validating your self-hosted Membrane installation. Generate this token from your organization settings in console. The token is validated against Membrane's cloud API on startup. | sht\_abc123... |
| Container | Scaling Approach | Recommended Values |
|---|---|---|
| Console | Fixed number of instances to ensure availability and zero-downtime updates. | Instances: 2 |
| UI | Fixed number of instances to ensure availability and zero-downtime updates. | Instances: 2 |
| Orchestrator | Fixed number of instances to ensure availability and zero-downtime updates. | Instances: 2 |
| API | Dynamic scaling based on resource usage. Monitor memory and CPU usage to determine scaling needs. | Threshold: 50% Min instances: 2 |
| Instant Tasks Worker | Dynamic scaling based on the number of active and waiting tasks, using a modifier to adjust the scaling sensitivity. Pseudocode:`avg(instant_tasks_worker_utilization_rate)` | Threshold: 0.75 Min instances: 2 |
| Queued Tasks Worker | Dynamic scaling based on workers utilization rate. Pseudocode:`avg(queued_tasks_worker_utilization_rate)` | Threshold: 0.85 Min instances: 2 |
| Custom Code Runner | Dynamic scaling based on job spaces availability. Monitor the number of total and remaining job spaces and auto scale maintain a certain rate. Pseudocode: `(custom_code_runner_total_job_spaces -custom_code_runner_remaining_job_spaces ) / custom_code_runner_total_job_spaces` | Threshold: 0.45 Min instances: 2 |
## Connector Management ### Automated Deployment Use [Membrane CLI](https://www.npmjs.com/package/@membranehq/membrane-cli) to migrate connectors from cloud to self-hosted environments. ### Manual Deployment Upload connector .zip archives through the Console UI via Integrations > Apps > Upload Connector. ## Troubleshooting For enhanced debugging output, add `DEBUG_ALL=1` to any container's environment variables. ## Helm
### Setting Up Registry Access 1. Login to Helm registry ``` helm registry login harbor.getmembrane.com \ --username
## Versions and Changelog ### Latest Version: 0.2.4
**Lookups with dynamic schemas** Lookups support dynamic schemas (see [Data Schemas](/docs/references/data-schemas) for what it is), but with restrictions. Say, your schema looks like this: ```yaml theme={null} type: object properties: referenceType: type: string referenceId: type: string referenceCollection: key: $var: referenceType ``` It has a reference to a collection determined dynamically. Lookups will work for this schema, but only if variables are provided statically. For example, this lookup will work: ```yaml theme={null} referenceType: contacts referenceId: $lookup: query: email: $var: $.email ``` But this lookup will not work because referenceType is dynamic and cannot be used to resolve referenceId lookup: ``` referenceType: $var: $.type referenceId: $lookup: query: email: $var: $.email ```
### \$eval This formula evaluates a value using one of supported operators and returns `true` or `false` depending on the result. Example: ```yaml theme={null} condition: $eval: $var: status is: Open ``` All \$eval formulas have the same form: ```yaml theme={null} $eval:
This guide shows you how you can implement a custom connection UI ## 1. Get Auth Options To get information about what to ask the user in order to create a connection, fetch connection options: ```javascript theme={null} const integration = await membrane.integration('hubspot').get() // Fetch connection options const connectionOptions = await membrane.post('/connection-options', { integrationId: integration.id, }) ```
For simplicity, we'll assume there is only one auth option. If there are more, you can use the same logic for each of them. If there are zero options, it means authentication is not configured and you need to edit or change the connector. Each connection option contains: * `key` – Unique identifier for this auth option (pass to `authOptionKey` when connecting) * `type` – The authentication type (e.g., 'oauth2', 'client-credentials') * `title` – Human-readable name for this auth option * `description` – Description explaining this auth method * `inputSchema` – [Data Schema](/docs/references/data-schemas) of the parameters required to create a connection. It will be empty if parameters are not required. ## 2. Connection Parameters UI You can use your preferred way of converting [JSON Schema](https://json-schema.org/) into a form. For example, you can extract a list of fields from the schema and simply display an input for each: ```javascript theme={null} function ConnectionForm() { const [input, setInput] = useState({}) const schema = { type: 'object', properties: { email: { type: 'string' }, apiKey: { type: 'string' }, }, } const fields = Object.keys(schema.properties) return ( <> {fields.map((field) => (
setInput({ ...input, [field]: e.target.value })}
/>
))}
)
}
```
If a connection doesn't have parameters, you can skip this step. ## 3. Creating a Connection When you have collected connection input, you can create a connection: ```javascript theme={null} const connection = await membrane.integration('hubspot').connect({ input }) ```
> This code may open a new window if it is required by the authentication process. > Make sure this code runs inside a user action handler (e.g. `onClick`), otherwise the browser may block the new window.
**Redirect instead of a new window** When you need to avoid opening a new window, you can use redirect instead. Pass `sameWindow: true` and `redirectUri` options. The URI will be used for redirection after the connection is created or fails. Added query parameters: * For successful creation, the `connectionId` will be added * For failures, `error` will contain the error message and `errorData` will contain the JSON stringified error payload ```javascript theme={null} const connection = await membrane.integration('hubspot').connect({ input, sameWindow: true, redirectUri: window.location.href, }) ```
## 4. Putting it all together Here is a simple UI component that displays the connection parameters and creates a new connection: ```javascript theme={null} import { useState, useEffect } from 'react' import { useIntegration, useMembrane } from '@membranehq/react' function Component({ integrationKey }) { // For this to work, wrap this component in
Error: {error.message}
} // Wait until the spec and connection options load if (!integration || !connectionOptions) { returnLoading...
} // Display only the first option const option = connectionOptions[0] if (!option) { returnNo auth options found for this integration
} // Get connection input schema const schema = option.inputSchema // Simplified way to get the list of connection parameters. const fields = schema ? Object.keys(schema.properties ?? {}) : [] async function connect() { setConnecting(true) try { const connection = await membrane.integration(integrationKey).connect({ input: connectionInput, authOptionKey: option.key, }) setConnection(connection) } finally { setConnecting(false) } } return (
{fields.length > 0 && (
)
}
```
Connection Parameters:
{fields.map((field) => (
)}
{connecting ? Connecting... : }
{connection && (
setConnectionInput({
...connectionInput,
[field]: e.target.value,
})
}
/>
))}
Connected!
Connection Id: {connection.id}
)}
Connection Id: {connection.id}
## 5. Re-connecting When a connection becomes disconnected, you can re-connect it using the same code as when creating a new connection: ```javascript theme={null} const connection = await membrane.integration('hubspot').connect({ input }) ```
## Multiple Connections for the same target By default, a `connect(...)` call reuses the existing connection for the same tenant when one exists. This applies whether you target an integration (`integrationId` / `integrationKey`), a connector (`connectorId` / `connectorKey`), or an external app (`externalAppId` / `externalAppKey`). Set `allowMultipleConnections: true` on the `connect` method call to always create a new connection instead of reusing an existing one. # Custom Connector Parameters Source: https://docs.getmembrane.com/docs/ways-to-use-membrane/embedded-ui/connection-ui/custom-connector-parameters Custom connector parameters allow you to override or extend the integration's default connector configuration on a per-connection basis. These are developer-provided values that customize how the connector behaves for specific connections. ## Use Cases Common use cases for custom connector parameters include: * **Custom OAuth scopes** for specific connection needs * **Dynamic environment selection** if you want to programmatically decide whether to use sandbox/prod environment without asking user. * **Having different versions of connector behavior** for different connections that don't require user input. ## Important Notes * Custom connector parameters are **developer-provided**, not user-editable fields * They are stored with the connection and used for all API calls through that connection * They take precedence over the integration's default connector parameters * They are optional - connections work without them using default integration settings *** ## Method 1: Using ui.connect() When you want to open the connection UI with custom connector parameters: ```javascript theme={null} await membrane.ui.connect({ integrationKey: 'hubspot', allowMultipleConnections: true, connectorParameters: { scopes: ['contacts', 'deals', 'companies'], // Custom OAuth scopes }, }) ```
## Method 2: Using connect() For programmatic connection creation with custom parameters: ```javascript theme={null} const connection = await membrane.integration('hubspot').connect({ input: { // User-provided connection input apiKey: 'user-api-key', }, connectorParameters: { // Developer-provided connector customizations scopes: ['contacts', 'deals', 'companies'], }, }) ```
## Method 3: Backend connection (no front-end SDK) For backend-to-backend integrations or when not using the frontend SDK: ### HTML Form Example ```html theme={null} ``` # MCP Source: https://docs.getmembrane.com/docs/ways-to-use-membrane/mcp Membrane provides a cloud MCP server that exposes its API as tools for AI agents. Your agent gets access to all Membrane operations — managing connections, running actions, querying data, and more. ## Setup Add Membrane's MCP server to your agent's configuration: ``` https://api.getmembrane.com/mcp/integrate-anything ``` **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json theme={null} { "mcpServers": { "membrane": { "type": "url", "url": "https://api.getmembrane.com/mcp/integrate-anything" } } } ``` **Cursor** (`.cursor/mcp.json` in your project): ```json theme={null} { "mcpServers": { "membrane": { "type": "url", "url": "https://api.getmembrane.com/mcp/integrate-anything" } } } ``` For other MCP clients, use the URL above and follow your client's configuration format. ## Authentication The MCP server supports OAuth — your agent will prompt you to log in when it first connects. If your MCP client doesn't support OAuth, you can authenticate by adding a Bearer token in the `Authorization` header: ``` Authorization: Bearer eyJhbGciOiJIUzUxMiIs... ``` As a last resort, append the token to the URL: ``` https://api.getmembrane.com/mcp/integrate-anything?token=eyJhbGciOiJIUzUxMiIs... ``` See [Authentication](/docs/how-membrane-works/authentication) for how to get a token. # REST API Source: https://docs.getmembrane.com/docs/ways-to-use-membrane/rest-api Use the REST API to access all Membrane operations — connections, actions, events, data, and more. ## Making API Requests To make API requests, you need a Membrane Token. You can generate in your code or in \[Console]. See [Authentication](/docs/how-membrane-works/authentication) for more details. ```bash theme={null} curl https://api.getmembrane.com/self \ -H "Authorization: Bearer YOUR_TOKEN" ``` See [API Reference](/reference) for the full list of available API endpoints and their inputs/outputs. ## OpenAPI Spec The full OpenAPI specification is available at: ``` https://api.getmembrane.com/-json ``` ## API Versioning The API uses `X.Y` versioning. The major version changes when there are breaking changes, and the minor version changes with any updates. Include the `API-Version` header to pin a specific version: ```bash theme={null} curl https://api.getmembrane.com/self \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "API-Version: 2.1" ``` See the [Changelog](https://changelog.getmembrane.com) for version history and changes. # JavaScript SDK Source: https://docs.getmembrane.com/docs/ways-to-use-membrane/sdk The Membrane JavaScript SDK provides typed accessors for all Membrane resources. It works in both Node.js and browser environments. ## Install ```bash theme={null} npm install @membranehq/sdk ``` ## Initialize ```javascript theme={null} import { MembraneClient } from '@membranehq/sdk' // With a static token const membrane = new MembraneClient({ token: process.env.MEMBRANE_ACCESS_TOKEN, }) // With dynamic token fetching — for long-lived environments (like web pages) // where the token may expire and needs to be refreshed const membrane = new MembraneClient({ fetchToken: async () => { const response = await fetch('/api/membrane-token') const { token } = await response.json() return token }, }) ``` See [Authentication](/docs/how-membrane-works/authentication) for how to get an access token. ## Usage ```javascript theme={null} // List integrations const integrations = await membrane.integrations.find() // Get a specific connection const connection = await membrane.connection('hubspot').get() // Run an action const result = await membrane.action('create-contact').run({ email: 'jane@example.com', name: 'Jane', }) // Open connection UI await membrane.ui.connect({ integrationKey: 'salesforce' }) ``` ## SDK Reference See the [SDK Reference](https://console.getmembrane.com/ref/sdk/index.html) for the full list of accessors, methods, and types. # CSP Rules Source: https://docs.getmembrane.com/docs/ways-to-use-membrane/sdk/csp-rules ## Configuring Your Content Security Policy for Membrane's JavaScript SDK When using **Membrane's JavaScript SDK** in your application, you'll need to configure your **Content Security Policy (CSP)** to allow communication with our services. This article outlines the necessary CSP rules to add for proper functionality. *** ### Required CSP Rules Add the following domain to your Content Security Policy under these directives: * **connect-src** * **child-src** * **form-action** The domain to whitelist is: `api.getmembrane.com` *** ### Example CSP Configuration Here's an example of how your CSP rules might look after adding these directives: ```plaintext theme={null} Content-Security-Policy: connect-src 'self' api.getmembrane.com; child-src 'self' api.getmembrane.com; form-action 'self' api.getmembrane.com; // ... other existing rules ... ``` *** ### Why These Rules Are Needed * **connect-src**: Allows the SDK to make API calls to Membrane's servers. * **child-src**: Permits the loading of necessary resources from Membrane. * **form-action**: Required for submitting sensitive data to our API in certain cases. *** ### Additional Considerations There are no region-specific domains or additional rules required for the JavaScript SDK. However, it's always a good practice to verify these settings with your application security team to ensure they align with your organization's security policies. *** ### Further Resources For more information about our SDK, you can refer to the following documentation: * [SDK Documentation](https://console.getmembrane.com/ref/sdk/index.html) * [React Integration Documentation](https://console.getmembrane.com/ref/react/index.html) If you encounter any issues or have further questions about CSP configuration for Membrane, please don't hesitate to contact our support team.
{integrations?.map((integration) => (
)
}
```
### Available Hooks
| Hook | Description |
| - | - |
| `useMembrane` | Get the MembraneClient instance from context |
| `useIntegrations` / `useIntegration` | List or get integrations |
| `useConnections` / `useConnection` | List or get connections |
| `useActions` / `useAction` | List or get actions |
| `useActionInstances` / `useActionInstance` | List or get action instances (per-tenant) |
| `useFlows` / `useFlow` | List or get flows |
| `useFlowInstances` / `useFlowInstance` | List or get flow instances |
| `useFlowRuns` / `useFlowRun` | List or get flow run history |
| `useDataSources` / `useDataSource` | List or get data sources |
| `useDataSourceInstances` / `useDataSourceInstance` | List or get data source instances |
| `useFieldMappings` / `useFieldMapping` | List or get field mappings |
| `useFieldMappingInstances` / `useFieldMappingInstance` | List or get field mapping instances |
| `useDataLinkTables` / `useDataLinkTable` | List or get data link tables |
| `useDataLinkTableInstances` / `useDataLinkTableInstance` | List or get data link table instances |
| `useAppEventTypes` / `useAppEventType` | List or get internal event types |
| `useAppEventSubscriptions` / `useAppEventSubscription` | List or get internal event subscriptions |
| `useAppDataSchemas` / `useAppDataSchema` | List or get app data schemas |
| `useAppDataSchemaInstances` / `useAppDataSchemaInstance` | List or get app data schema instances |
| `useExternalEventSubscriptions` / `useExternalEventSubscription` | List or get external event subscriptions |
| `useCustomers` / `useCustomer` | List or get customers |
| `usePackages` / `usePackage` | List or get packages |
| `useScreen` | Access UI screens |
| `useConnectorSpec` | Get connector specification |
| `useDataCollectionSpec` | Get data collection specification |
## UI Components
Pre-built components for common integration UIs:
```jsx theme={null}
import { Integrations, DataBuilder } from '@membranehq/react'
// Render a full integrations list
{integration.name}
))}
## Styling component parts Styling is supported, see [Components](/docs/ways-to-use-membrane/sdk/react/ui-components) page for more details. The `ComboBox` component is made of multiple smaller components, here is a list of parts for each: **Component:**\ dropdown | Part className | Description | | - | - | | `dropdown__popover-container` | Main container of a dropdown. Emits keyboard navigation events | | `dropdown__content` | Dropdown content container | | `dropdown__panel` | Section panel. Can be multiple. Can be nested | | `dropdown__search-input` | Search input element | | `dropdown__search-divider` | Divider between search input and rest of elements | | `dropdown__list` | Items list container | | `dropdown__items-list-header` | Items list header | | `dropdown__item` | Single list item container | | `dropdown__item-title` | List item title | | `dropdown__no-options-heading` | Heading title for empty search result | | `dropdown__error-heading` | Heading for error when options failed to load | | `dropdown__error-heading-icon` | Error heading icon | | `dropdown__info-heading` | Heading for unsupported states within the dropdown | | `dropdown__info-heading-icon` | Info heading icon | | `dropdown__loading-item-container` | List item skeleton container | | `dropdown__loading-item-icon` | List item icon skeleton | | `dropdown__loading-item-title` | Loading item title skeleton | # Data Input Source: https://docs.getmembrane.com/docs/ways-to-use-membrane/sdk/react/data-input Data Input is used to let users enter data that fits a specific [Data Schema](/docs/references/data-schemas) with optional use of variables defined by another Data Schema. It supports complex schemas, lookups, data transformation formulas, and other features useful for configuring integrations. ```javascript theme={null} import { DataInput, DataSchema } from "@membranehq/react"; export function PlainDataInputExample() { const [value, setValue] = useState
## Nested Components * [Combobox](/docs/ways-to-use-membrane/sdk/react/combobox) # Hooks Source: https://docs.getmembrane.com/docs/ways-to-use-membrane/sdk/react/hooks Hooks let you interact with Membrane resources from React components. They handle async operations and state management automatically. Get the Membrane client instance with `useMembrane()`: ```jsx theme={null} import { useMembrane } from '@membranehq/react' function MyComponent() { const membrane = useMembrane() // Use membrane.ui.connect(), membrane.action(), etc. } ``` ## Hooks for individual entities Hooks for individual entities are used to fetch and manage data for a single workspace element such as [Flow](/reference/workspace-elements/flows) or [Field Mapping](/reference/workspace-elements/field-mappings). They have the following structure: ```jsx theme={null} useFlow(selector: FlowSelector): { flow: undefined | Flow; apply: ((integrationKeys: string[]) => Promise
selector |
String or object that uniquely identifies the entity. It can be the entity's ID or a combination of entity key and connection selector. |
flow |
Current state of the entity |
apply |
Applies universal entity to selected integrations |
reset |
Resets entity to its initial state (only works for entities that have parents) |
refresh |
Refresh entity data from the server |
accessor |
SDK-provided object for working with the entity. |
loading |
Whether initial data is being loaded |
saving |
Whether entity is being saved to the server |
error |
Error that occurred during last operation |
refreshing |
Whether entity is being refreshed from server |
create |
Create new entity |
patch |
Partially update entity |
put |
Fully update entity (replace all its properties with provided ones) |
archive |
Archive (soft delete) entity |
query |
Query for fetching / filtering the list of entities |
items |
Current list of entities (including all the loaded pages) |
loadMore |
Load the next page of entities from the server (if there is no more pages - nothing will happen) |
loadingMore |
Whether more entities are being loaded from the server |
refresh |
Refresh the list of entities from the server (if multiple pages were fetched previously - only the first page will remain after the refresh) |
loading |
Whether the list is being loaded from the server |
error |
Error that occurred during the last operation |
Loading...
if (error) return Error: {error.message}
return (
-
{items?.map((conn: Connection) => (
- {conn.name} {conn.disconnected ? '(disconnected)' : ''} ))}
## Props: `FloatingPortalBoundary`
| Prop | Type | Description |
|---|---|---|
children |
React.ReactElement |
Components Children. Accepts only single child. |
id |
string | undefined |
Custom ID for boundary container. If not passed - useId is used. |
Loading...
## Action Structure Action has the following properties: * **`inputSchema`** – [Data Schema](https://.integration.app/docs/references/data-schemas) describing the payload that will be validated when you run the action. * **`type`** – action type that maps to a [Function Type](/docs/references/functions) that implements the `run` function of this action. * **`config`** – implementation of the `run` function. * **`outputSchema`** - defines expected output of the action. * **`customOutputSchema`** - overrides the default value of `outputSchema`. If customOutputSchema is set, outputSchema will always equal `customOutputSchema` ## Run Function Action interface provides one function: [Run](/docs/references/functions/function-types/run-action). The implementation of this function is configured with two properties: `type` and `config`. The `run` function receives the following arguments: * `input` - action input provided when running the action. Action types map to [Function Types](/docs/references/functions) and let you choose how action's `run` function is implemented. If not sure what action type to use, [Javascript](/docs/references/functions/function-types/javascript) is the most versatile type that lets you do anything, and [API Request to External App](/docs/references/functions/function-types/api-request-to-external-app) is commonly used to configure API requests if it's all that action needs to do. | Type | Description | Function Type | | :- | :- | :- | | `run-javascript` | Runs custom JavaScript (or TypeScript) code | [JavaScript](/docs/references/functions/function-types/javascript) | | `api-request-to-external-app` | Makes API requests to the external app with authentication applied automatically | [API Request to External App](/docs/references/functions/function-types/api-request-to-external-app) | | `api-request-to-your-app` | Makes API requests to your Internal API | [API Request to Your App](/docs/references/functions/function-types/api-request-to-your-app) | | `http-request` | Makes arbitrary HTTP requests to any endpoint | [HTTP Request](/docs/references/functions/function-types/http-request) | | `list-data-records` | List records in a data collection page by page | [List Data Records](/docs/references/functions/function-types/list-data-records) | | `find-data-record-by-id` | Find a record in a data collection by ID | [Find Data Record By ID](/docs/references/functions/function-types/find-data-record-by-id) | | `search-data-record` | Search data records by a query string | [Search Data Record](/docs/references/functions/function-types/search-data-record) | | `match-data-record` | Find a data record with fields matching a query | [Match Data Record](/docs/references/functions/function-types/match-data-record) | | `create-data-record` | Create a new data record | [Create Data Record](/docs/references/functions/function-types/create-data-record) | | `update-data-record` | Update an existing data record | [Update Data Record](/docs/references/functions/function-types/update-data-record) | | `delete-data-record` | Delete a data record by id | [Delete Data Record](/docs/references/functions/function-types/delete-data-record) |
## Using Actions Action has only one function: `run`. To run an action, you need to provide an input that matches its `inputSchema`. As a result, you will get an output that matches its `outputSchema`. All the action runs are recorded as [Action Run Logs](/reference/workspace-elements/action-run-logs). See full API reference here: [Actions API Reference](https://.integration.app/update/reference/workspace-elements/actions). ## API Operations | Operation | Method | Endpoint | Description | | - | - | - | - | | [Act](/reference/workspace-elements/act) | POST | `/act` | Run an action (canonical run path) | | [List all actions](/api-reference/actions/list-actions) | GET | `/actions` | Retrieve all workspace actions | | [Get action by ID](/api-reference/actions/get-action-by-selector) | GET | `/actions/{selector}` | Get specific action details | | [Create a new action](/api-reference/actions/create-a-new-action) | POST | `/actions` | Create a new workspace action | | [Replace action](/api-reference/actions/replace-action-completely) | PUT | `/actions/{selector}` | Replace action configuration | | [Patch action](/api-reference/actions/update-action-partially) | PATCH | `/actions/{selector}` | Update action partially | | [Clone action](/api-reference/actions/clone-action) | POST | `/actions/{selector}/clone` | Clone an existing action | | [Run action](/reference/workspace-elements/act#legacy-post-actionsselectorrun) | POST | `/actions/{selector}/run` | Execute an action (**deprecated** — use `/act`) | | [Reset action](/api-reference/actions/reset-action) | POST | `/actions/{selector}/reset` | Reset action to default state | | [Export action](/api-reference/actions/export-action-flat-interface) | GET | `/actions/{selector}/export` | Export action configuration | | [Get action dependencies](/api-reference/actions/get-dependencies-of-action-flat-interface) | GET | `/actions/{selector}/dependencies` | Get action dependencies | | [Restore action](/api-reference/actions/restore-action-flat-interface) | POST | `/actions/{selector}/restore` | Restore archived action | | [Refresh actions](/api-reference/actions/refresh-action) | POST | `/actions/refresh` | Refresh action definitions | | [Archive action](/api-reference/actions/archive-action) | DELETE | `/actions/{selector}` | Archive an action | # App Data Schemas Source: https://docs.getmembrane.com/reference/workspace-elements/app-data-schemas App Data Schemas is a [Data Schema](/docs/references/data-schemas) that can be shared across multiple places in your integrations.\ It can be used for [Field Mappings](/reference/workspace-elements/field-mappings) or as a component for any other schema used in an integration. ## Referencing Schema You can reference an App Data Schema in other schemas using the `$ref` formula: ```json theme={null} { "type": "object", "properties": { "name": { "type": "string" }, "user": { "$ref": "schemas/user" // Reference to the "user" App Data Schema } } } ``` ## User-specific Schema Whenever a schema is used in a context of a specific user, and you provided an HTTP request, it will be executed on behalf of the current user. The response to this request should be a JSON-encoded [Data Schema](/docs/references/data-schemas). You can find the latest request and response for a given user on the [App Data Schema Instances](https://console.integration.app/w/0/deployments/app-data-schema-instances) page. # Internal Event Logs Source: https://docs.getmembrane.com/reference/workspace-elements/app-event-logs # Internal Events Source: https://docs.getmembrane.com/reference/workspace-elements/app-events Internal Events let Membrane know when something happens in your app. They can be used to trigger Flows using [Internal Event Trigger](https://membrane-docs.readme.io/docs/nodes#/app-event-trigger). ## Internal Event Types To use Internal Events, you need to define one or more Internal Event Types. You can do it on the [Internal Event Types](https://console.integration.app/w/0/event-types) page. Each Internal Event Type has: * **Schema** – a [Data Schema](/docs/references/data-schemas) describing the event's contents. * **Example** – an example of the event's contents matching the Schema. You can use Example to generate schema. ## Sending Events to Membrane ### Global Webhook Use Global Webhook to send internal events to Membrane in a centralized (not per-user) way. Simply make an HTTP request of any type to the webhook URI and the event will be captured and processed. ```bash theme={null} curl --request POST \ --url https://api.integration.app/{GLOBAL_WEBHOOK_URI} \ --header "Authorization: Bearer {CUSTOMER_TOKEN}" \ --header "Content-Type: application/json" \ --data '{"eventType": "order.created", "orderId": "123"}' ``` **Associating Events with Tenants** When you send an event to the Global Webhook, Membrane needs to know which tenant the event belongs to. There are three ways to specify this, in order of priority: 1. **Authentication Token (Recommended)** – Include the tenant's authentication token in the `Authorization` header. Membrane will automatically extract the tenant ID from the token. 2. **Tenant ID Formula** – Configure a formula in the Internal Event Type settings that extracts the tenant ID from the event payload. This is useful when you cannot include an authentication token in the request. 3. **User ID Formula (Legacy)** – For backward compatibility, you can use the older "User ID Formula" field which works the same way as Tenant ID Formula. If none of these methods provide a tenant ID, the event will be rejected. ### Per-Tenant Subscriptions If instead of a Global Webhook, you want to use per-user webhooks or if you already have an API that allows per-user event subscriptions, you can configure subscriptions for your Internal Event. When configured, Membrane: 1. Makes an HTTP request to your application's subscription API 2. Provides a unique webhook URL in the request (available as `{{webhookUri}}` variable) 3. Expects your application to send events to that specific webhook URL 4. Tracks the subscription request and response for troubleshooting You can use [Tenant Fields](/docs/how-membrane-works/tenants) and `webhookUri` variables to configure the request. The request will be called the first time this Internal Event Type is used for a given User. You can find the subscription request and response, as well as other information about subscriptions on the [Subscriptions](https://console.integration.app/w/0/deployments/app-event-subscriptions) page. ### Batch Events If the body of the request your app sends to Membrane is an array, it will be treated as multiple events. For global webhooks with batch events, each event can be associated with a different tenant by including tenant identification in each event payload. ## How Subscriptions Work Internal event subscriptions are created when a [Flow](/reference/workspace-elements/flows) has a trigger that reacts to Internal Events and the flow is enabled. When you enable a Flow that uses an Internal Event Trigger node, Membrane automatically: 1. Creates an Internal Event Subscription for the specified Internal Event and Tenant. 2. If configured, makes an HTTP subscription request to your application's API. 3. Generates a unique webhook URL for receiving events. The subscription is automatically disabled (and unsubscribed) when there are no more flows that need it. ### Automatic De-duplication Membrane automatically de-duplicates subscriptions. If multiple Flow Instances need the same Internal Event Type for the same tenant and instance key, only one subscription is created and shared between them. For example: * Flow A and Flow B both trigger on "Order Created" events for Tenant X * Only one Internal Event Subscription is created * Both flows are launched when an event arrives * The subscription remains active until both flows are disabled ## Monitoring and Troubleshooting ### Viewing Subscriptions Navigate to [Internal Event Subscriptions](https://console.integration.app/w/0/deployments/app-event-subscriptions) to see: * All active and inactive subscriptions * Subscription status (subscribed/unsubscribed) * The webhook URL for each subscription * Subscription and unsubscription request/response history * Associated Internal Event Type and tenant ### Viewing Events Navigate to [Internal Events](https://console.integration.app/w/0/activity/app-events) to see: * All received events * Which subscription received each event * Event payload and timestamp * Which Flows were triggered * Execution status of triggered Flows ### Flow Was Not Launched If you expected a webhook to launch a flow, but it didn't: **Step 1: Check Logs** Go to the [Webhook Logs](https://console.integration.app/w/0/activity/external-webhook-logs) and check if the events you expected are there. Use filters to narrow down the list. If you found the record, check its details: * Is it associated to the correct App User? * Does it have the data you expected? **Step 2: Check Flow Node Configuration** If you found the event in logs but it didn't trigger the expected flow: * Does the trigger use the right webhook? Check node dependencies on the Flow Instance page. * Does it have a filter that excludes the event? ### Webhook Events Do Not Appear in Logs **Step 1: Check Subscription** If you are using a webhook with subscription, find the subscription by Webhook and User, and check its status. Is it subscribed successfully? **Step 2: Trigger the Webhook Manually** Make an HTTP request to the webhook URL: * If using a subscription – find the webhook URL on the corresponding subscription page. * If not – use the URL from the webhook page. ### Webhook Subscription Is Not Created Find it on the [Subscriptions](https://console.integration.app/w/0/deployments/app-event-subscriptions) page and check the latest request and response. If everything looks correct, the problem is likely on your app's side. You can try deleting the subscription and creating it again to troubleshoot. # Connections Source: https://docs.getmembrane.com/reference/workspace-elements/connections Connections represent credentials and configuration used to access integrations on behalf of your tenants. They have the following properties: | Property | Description | | - | - | | `id` | Unique identifier of the connection. | | `name` | Name of this connection. It can be set by you when creating the connection or assigned automatically. | | `type` | Connection backing. Omitted (or `connector`) for integration-backed connections; `mcp` for a connection to an arbitrary [MCP server](#mcp-connections). | | `integrationId` | Identifier of the integration connection is created for. Not set for `mcp` connections. | | `authOptionKey` | If integration offers multiple authentication options, this property will contain the key of the selected option. | | `input` (secret) | Connection input provided by the tenant when creating the connection. | | `credentials` (secret) | Credentials required to access the external API. | | `connectorParametres` (secret) | Connector parameters provided by the integration at the time of connection creation. | | `disconnected` | Set to true if connection was disconnected (cannot be used to make API requests). | | `error` | Contains error details if connection is disconnected. | | `nextCredentialsRefreshAt` | Timestamp when credentials are scheduled to be automatically refreshed (if auto-refresh is enabled). | | `nextRetryTimestamp` | Timestamp when next reconnection attempt is scheduled (if connection is disconnected). | | `retryAttempts` | Current retry attempt count (0-10) for auto-reconnect. | ## Creating Connections > We recommend using [Connection UI](/docs/ways-to-use-membrane/embedded-ui/connection-ui/custom-connection-ui) implemented with our drop-in components or Javascript SDK.\ > Use the flow below only when you know what you are doing. To create a new connection or refresh credentials for an existing connection, follow the steps described below.\ They work in the same way for every connector regardless of the app that is being connected. ### Connector Auth Spec You can get information about how authentication works in a given connector from its specification. Look for the following fields: * `auth.type` - type of authentication supported by the connector. Possible values are: * `client-credentials` - Authentication based on credentials user enters in the UI. * `oauth1` - OAuth1 authentication * `oauth2` - OAuth2 authentication * `ui` - information about what to display user in the UI when authenticating. ### Authentication Flow To authenticate a user you need to do the following: 1. Collect connection parameters from the user. They need to match `ui.schema`. 2. Send a **POST** request to `https://api.getmembrane.com/connect` with the parameters described below. If `auth.type` is `client-credentials`, you can submit this request from a hidden iframe. If not, you need to open it in a new window visible to the user. If you need to start the flow with a plain browser redirect (which uses GET), use the legacy `https://api.getmembrane.com/connection-popup` endpoint instead. Add the following parameters to the request (as query parameters or in the body): * token - your tenant's [Access Token](/docs/how-membrane-works/authentication) * requestId - a unique id of this authentication request. It will be used in the callback to separate callbacks from different requests. Note: providing this parameter will result in window being closed after connection is created. If you want it to behave differently (for example, redirect to another URL), you cannot use this parameter. * integrationKey - key of the integration you want to authenticate against. * connectionId (optional) - id of the connection you want to refresh credentials for (if you want to do it for a specific connection) * input (optional) - parameters provided by user in the connection UI, JSON-encoded. ### Custom Callback URL In some cases you need to use a custom Callback URL instead of standard `https://api.getmembrane.com/oauth-callback`. These situations include: * When you need to approve your app and callback URL needs to be on your domain (for example, Google requires that). * You want to create a custom installation logic for some application stores (for example, [Pipedrive app installation flow](https://pipedrive.readme.io/docs/app-installation-flows)). * When you want to do any other custom handling of oAuth callback. You can set custom callback URI in the integration settings. It will be used for all connections created for this integration.
## Configuring Intervals The [custom pull](/reference/workspace-elements/data-collections/data-collection-events/data-collection-events-pull-latest) and [pull-latest records](/reference/workspace-elements/data-collections/data-collection-events/data-collection-events-pull-latest) implementation types use a default interval of **300 seconds**, while **Full scan** uses a default interval of **10,800 seconds**. These intervals can be configured at either the **trigger node level** (when a data source is not used) or the **data source level**(when a data source is used) using the **pull update interval** and **full sync interval** options. Refer to the [limits page](/docs/managing-membrane/limits#external-event-pulls) to see the minimum allowed interval.
Data Source Instance has the following properties: | Property | Description | | - | - | | `id` | Unique identifier of the instance. | | `path` | Path to the Data Collection the data source is pointing to. | | `defaultPath` | Path to the Data Collection the data source is pointing to by default. | | `udm` | A Universal Data Model records in this data source will be transformed to / from. | | `pullUpdatesIntervalSeconds` | How often the data source will be pulled for new events. | | `fullSyncIntervalSeconds` | How often the data source will be fully synced (to get events that require a full sync). | | `subscriptions` | Information about active subscriptions to Data Source Events (see below for details). | | `isCustomized` | Whether this data source was customized by your tenant (path was changed, etc.) | ## Advanced Options Data Sources can be configured with the following advanced options: * Pull Updates Interval – number of seconds between each pull for updates such as new events (except events that require Full Sync). Setting it lower will increase the number of API requests and may result in hitting rate limits. * Full Sync Interval – number of seconds between full syncs of the data source. Full Sync is a very heavy operation since it pulls ALL the data from the data source. It generates events for subscriptions that require Full Sync. ## API Here is how to interact with data in external applications using [Data Sources](/reference/workspace-elements/data-sources). ### Create ```javascript theme={null} await membrane.connection('hubspot').dataSource('{DATA_SOURCE_KEY}').create() ``` ### Get ```javascript theme={null} const dataSourceInstance = await membrane .connection('hubspot') .dataSource('{DATA_SOURCE_KEY}') .get({ autoCreate: true }) ```
### Update ```javascript theme={null} await membrane.connection('hubspot').dataSource('{DATA_SOURCE_KEY}').patch('{INPUT}') ```
### Setup or Refresh ```javascript theme={null} await membrane.connection('hubspot').dataSource('{DATA_SOURCE_KEY}').setup() ```
### Reset ```javascript theme={null} await membrane.connection('hubspot').dataSource('{DATA_SOURCE_KEY}').reset() ```
### Archive ```javascript theme={null} await membrane.connection('hubspot').dataSource('{DATA_SOURCE_KEY}').archive() ```
## Navigating Data Source Instances Data Sources point to [Data Collections](/reference/workspace-elements/data-collections) in external apps.\ They let you store and customize data collection and their parameters per tenant. This page describes how to navigate data sources and configure them for your tenants.
The response will contain a `locations` property with a list of nested directories and collections.\ If there are too many to return at once, the response will also contain a `cursor` property. You have to pass it back to get the next page of results. To list locations inside a specific directory, pass its `path` to the `getLocations` method. ### Point Data Source to a Collection When a Data Source is created, it will point to a default collection (if one exists in the external app). You can change it by updating the `collectionKey` property of the Data Source: ```javascript theme={null} const dataSourceInstance = await membrane.connection('hubspot').dataSource('{DATA_SOURCE_KEY}').patch({ collectionKey: '{COLLECTION_KEY}', collectionParameters: '{COLLECTION_PARAMETERS}', }) ```
You can only update the `collectionKey` to point to a Collection. After you update `collectionKey`, accessing the data source's `collection` uses the new path. ### Data Collection Parameters Some collections have parameters. For example, a collection "Tasks by Project" may have a `projectId` parameter. If a collection has parameters, it will have a `parametersSchema` property.\ It is a [Data Schema](/docs/references/data-schemas) for its parameters. To apply parameters to a data collection, add them as a query string to the `path` property of the Data Source Instance, like this: ```json theme={null} { "path": "/data/tasks?projectId=123" } ``` ## Working with Data You can read and write data records using a Data Collection identified by the `collectionKey` property of the Data Source Instance. ## Multiple Data Source Instances per Connection By default, each pair of Connection and Data Source will have only one Data Source instance.\ If you change it (for example, set a `collectionKey`), it will apply to every place you use a given Data Source with a given connection. In some cases you may want to create multiple Data Source Instances for the same Connection and Data Source—\ for example, if you have multiple locations you want to import. This can be achieved by providing `instanceKey` when accessing a Data Source. Each `instanceKey` will create a new Data Source Instance. ```javascript theme={null} await membrane .connection('hubspot') .dataSource('{DATA_SOURCE_KEY}', { instanceKey: '{INSTANCE_KEY}' }) .get({ autoCreate: true }) ``` # External API Logs Source: https://docs.getmembrane.com/reference/workspace-elements/external-api-logs # Apps Source: https://docs.getmembrane.com/reference/workspace-elements/external-apps You can add, configure, and remove your integrations with external apps from the [Apps](/reference/workspace-elements/connectors) section of the console. When adding apps, you can choose from a list of supported integrations we have in our library or write in your own.
## Connector To interact with an external app, it needs a [connector](/reference/workspace-elements/connectors). For popular apps, you can usually find a connector in our library of public connectors.\ For less popular apps, you can create a custom connector using [Connector Builder](/reference/workspace-elements/connectors) or ask our Solutions team to do this for you (with a predictable cost and time). ### Configuring Connectors Some connectors may require you to configure them. In those cases, there will be configuration documentation you can follow:
### handle The handle function is called when data is sent to the webhook. Example: ``` export default async function handle({ data }) { return { events: [ { payload: data, selector: `user_id:${data.from_user_id}`, }, ], response: { status: 201, data: "Webhook received" } } } ``` **Arguments:** * `query` – object, webhook request query received from the external app * `data` – object, webhook request body received from the external app (parsed based on Content-Type) * `headers` – object, webhook request headers received from the external app * `parameters` – connector parameters configured on the integration the webhook belongs to * `rawBody` – string, raw unparsed body of the webhook request (useful for signature verification or when you need access to the original request body) **Result:** * `events` – list of events. Each event has the following properties: * `selector` (string) – selector to find matching external event subscriptions (see [External Events](/docs/managing-membrane/monitoring-troubleshooting/logs/external-events)) * `payload` – arbitrary event payload that will be passed to matched subscriptions. * `response` – object, optional HTTP response with properties: * `headers` – object * `status` – number * `data` – HTTP body (based on Content-Type) ## Global Webhook Event [External Events](/reference/workspace-elements/external-event-logs) implemented through global webhook look like this: ``` // events/event-key/spec.yml name: Event Name implementationType: global-webhook key: event-key methods: get-event-selector: implementationType: javascript ``` ### Functions The following functions can be implemented for events with `global-webhook` implementation type: **getEventsSelector** This method returns data that will be used to route the event to the correct connection. Supported implementation types: `javascript`, `mapping` Example: ``` export default async function getEventSelector({ apiClient }) { const response = await apiClient.get('users/me') return { globalWebhookKey: 'global-webhok-key', globalWebhookEventSelector: `user_id:${response?.id}`, } } ``` Function arguments: * `parameters` – object of parameters (matching `parametersSchema`) of this particular event. Return value is an object with the following fields: * `globalWebhookKey` – key of the global webhook defined in the connector (see [Global Webhooks](/reference/workspace-elements/external-events/global-webhook)) * `globalWebhookEventSelector` – string that is used to route the event to the correct subscription. This string typically needs to be generated dynamically based on the event parameters and information we can get from the current connection (using apiClient or credentials). When a global webhook handles a payload and returns events, it will be routed to a given [External Event Subscriptions](/reference/workspace-elements/external-events/external-event-subscriptions) if: * `globalWebhookKey` returned from this method matches the key of the global webhook * `globalWebhookEventSelector` returned from this method matches the event selector associated to the event returned by the `handle` method of the global webhook. # Webhook Events Source: https://docs.getmembrane.com/reference/workspace-elements/external-events/webhook This type of event subscribes to a webhook and then receives event notifications. ## Methods The following methods can be implemented for webhook events: ### Subscribe * **Method key:** `subscribe` * **Supported implementation types:** `javascript`, `rest-api-mapping`, `graphql-api-mapping` This function subscribes to events in the external app. **Arguments:** * `webhookUri` – string, URI webhooks should be sent to. It should be passed to the external app. * `parameters` – object, parameters (matching `parametersSchema`) of this particular event. **Result:** * `state` – object, subscription state. This state will be saved and passed as `state` to `unsubscribe` and `handle` functions. * `nextRefreshTimestamp` – number, optional, timestamp in milliseconds when the next refresh should be performed. Used to refresh the subscription if the external app requires it. Example: ```javascript theme={null} // Example: Subscribe to a webhook and return the webhookId. export default async function subscribe({ apiClient, webhookUri, parameters }) { const body = { webhookUri, '
See more: [Field Mapping UI](/reference/workspace-elements/field-mappings/field-mapping-instances) ## Creating & Configuring Instance via Membrane SDK Here is how to use Field Mapping Instances via Membrane SDK ### Create ```javascript theme={null} await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPING_KEY}').create() ```
### Get ```javascript theme={null} await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPINGS_KEY}').get() ```
### Update ```javascript theme={null} await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPING_KEY}').patch('{INPUT}') ```
### Set up / Refresh Updates to the base field mapping are automatically applied. If they aren't, you can use `.setup()` to manually pull merged updates from the base field mapping. ```javascript theme={null} await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPING_KEY}').setup() ```
### Reset This method resets the field mapping instance to its default state, erasing all the tenant configuration. ```javascript theme={null} await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPING_KEY}').reset() ```
### Archive ```javascript theme={null} await membrane.connection('hubspot').fieldMapping('{FIELD_MAPPING_KEY}').archive() ```
## Multiple Field Mapping Instances per Connection By default, every pair of Field Mapping and Connection will use the same Field Mapping Instance, which means that mapping values will be shared between them. If you want to use multiple different mapping values for the same pair of Field Mapping + Connection, you should use `instanceKey`. ```javascript theme={null} await membrane .connection('hubspot') .fieldMapping('{FIELD_MAPPINGS_KEY}', { instanceKey: '{INSTANCE_KEY}' }) .get({ autoCreate: true }) ```
When you apply `instanceKey` to a Field Mapping Instance, it will be automatically applied to the elements Field Mapping works with: Data Source, App Data Collection, etc. # Files Source: https://docs.getmembrane.com/reference/workspace-elements/files # Flow Runs Source: https://docs.getmembrane.com/reference/workspace-elements/flow-runs # Flows Source: https://docs.getmembrane.com/reference/workspace-elements/flows Flow represents a multi-step integration logic that can be triggered by events, on schedule, or via API. Flows consist of nodes and always start with a trigger node. Here is an example of a flow: ```yaml theme={null} name: Sync New Contacts key: sync-new-contacts nodes: contact-created: type: data-record-created-trigger name: Contact Created config: dataSource: collectionKey: contacts links: - key: transform-contact-data transform-contact-data: type: transform-data name: Transform Contact Data config: output: firstName: $var: input.contact-created.record.fields.firstName lastName: $var: input.contact-created.record.fields.lastName email: $var: input.contact-created.record.fields.email links: - key: send-contact-to-my-app send-contact-to-my-app: type: api-request-to-your-app name: Send contact to my app config: request: uri: https://myapp.com/api/new-contact method: POST body: contact: $var: $.input.transform-contact-data ```
## Flow Structure A flow consists of the following components: * **`name`** – Human-readable name of the flow. * **`key`** – Name of the flow to use in your code (unique within a workspace) * **`description`** – Optional description of what the flow does. * **`nodes`** – A dictionary of nodes that make up the flow. Each node has a unique key and contains configuration for its behavior. * **`parametersSchema`** – Schema of the flow parameters - useful for creating child flows from a parent template. * **`parameters`** – Parameters of the flow (match `parametersSchema`) * **`enabled`** – Whether the flow is enabled. * **`parentUuid`** – UUID of the parent flow (when this flow was created from a parent flow) * **`integrationUuid`** – UUID of the integration this flow is created for (only for flows that have an integration) * **`connectionUuid`** – UUID of the connection this flow is created for (only for flows that have a connection) * **`isCustomized`** – Whether the flow is customized compared to the parent (only for flows that have a parent) ### Node Structure Each node in a flow has the following properties: * **`type`** – Node type that defines what the node does (see [Node Types](#node-types) below). * **`name`** – Human-readable name describing what this node does. * **`config`** – Configuration specific to the node type. * **`concurrency`** – Number of concurrent runs allowed for this node (default: 1). * **`onError`** – Behavior when the node encounters an error: `stop` (default) or `continue`. * **`links`** – Array of links to downstream nodes. ### Links Links connect nodes together and control the flow of data. Each link has: * **`name`** – Optional name for the link. * **`key`** – Key of the target node to connect to. * **`filter`** – Optional filter to conditionally pass outputs to the target node. The value of the filter can use any formulas and has access to the same variables as the node's configuration, with additional `output` variable available that represents output of the current node.
## Node Types Nodes are the building blocks of flows. Each node type serves a specific purpose and can be configured to perform different operations. ### Triggers Triggers start the flow execution. Every flow must have at least one trigger node. Flows can have multiple triggers to reuse the same logic in different scenarios. | Type | Description | Documentation | | :- | :- | :- | | `api-trigger` | Launch flow via API with optional input | [API Trigger](/reference/workspace-elements/flows/trigger-nodes#api-trigger) | | `schedule-trigger` | Run flow on a recurring schedule | [Schedule Trigger](/reference/workspace-elements/flows/trigger-nodes#schedule-trigger) | | `app-event-trigger` | Launch flow when an event happens in your app | [Internal Event Trigger](/reference/workspace-elements/flows/trigger-nodes#internal-event-trigger) | | `data-record-created-trigger` | Run flow when a data record is created | [Data Record Created Trigger](/reference/workspace-elements/flows/trigger-nodes#data-record-created-trigger) | | `data-record-updated-trigger` | Run flow when a data record is updated | [Data Record Updated Trigger](/reference/workspace-elements/flows/trigger-nodes#data-record-updated-trigger) | | `data-record-deleted-trigger` | Run flow when a data record is deleted | [Data Record Deleted Trigger](/reference/workspace-elements/flows/trigger-nodes#data-record-deleted-trigger) | | `connector-event-trigger` | Launch flow on connector-specific events | [Connector Event Trigger](/reference/workspace-elements/flows/trigger-nodes#connector-event-trigger) | ### Function Nodes Function nodes perform operations on data, make API requests, or interact with external systems. | Type | Description | Documentation | | :- | :- | :- | | `list-data-records` | List all records from a data collection | [List Data Records](/reference/workspace-elements/flows/function-nodes#list-data-records) | | `find-data-record-by-id` | Find a single record by its ID | [Find Data Record By ID](/reference/workspace-elements/flows/function-nodes#find-data-record-by-id) | | `search-data-records` | Search for records using a query string | [Search Data Records](/reference/workspace-elements/flows/function-nodes#search-data-records) | | `lookup-data-record` | Look up a record by field values | [Lookup Data Record](/reference/workspace-elements/flows/function-nodes#lookup-data-record) | | `find-or-create-data-record` | Find existing record or create if not found | [Find or Create Data Record](/reference/workspace-elements/flows/function-nodes#find-or-create-data-record) | | `create-data-record` | Create a new data record | [Create Data Record](/reference/workspace-elements/flows/function-nodes#create-data-record) | | `update-data-record` | Update an existing data record | [Update Data Record](/reference/workspace-elements/flows/function-nodes#update-data-record) | | `delete-data-record` | Delete a data record | [Delete Data Record](/reference/workspace-elements/flows/function-nodes#delete-data-record) | | `create-data-link` | Create a link between records | [Create Data Link](/reference/workspace-elements/flows/function-nodes#create-data-link) | | `find-data-link` | Find a link between records | [Find Data Link](/reference/workspace-elements/flows/function-nodes#find-data-link) | | `delete-data-link` | Delete a link between records | [Delete Data Link](/reference/workspace-elements/flows/function-nodes#delete-data-link) | | `api-request-to-external-app` | Make authenticated API requests to external apps | [API Request to External App](/reference/workspace-elements/flows/function-nodes#api-request-to-external-app) | | `api-request-to-your-app` | Make API requests to your internal API | [API Request to Your App](/reference/workspace-elements/flows/function-nodes#api-request-to-your-app) | | `custom-http-request` | Make arbitrary HTTP requests | [Custom HTTP Request](/reference/workspace-elements/flows/function-nodes#custom-http-request) | | `run-javascript` | Execute custom JavaScript code | [Run JavaScript](/reference/workspace-elements/flows/function-nodes#run-javascript) | | `run-action` | Execute a predefined action | [Run Action](/reference/workspace-elements/flows/function-nodes#run-action) | | `integration-specific-operation` | Execute integration-specific operations | [Integration Specific Operation](/reference/workspace-elements/flows/function-nodes#integration-specific-operation) | ### Control Nodes Control nodes manage the flow of execution, transform data, and implement conditional logic. | Type | Description | Documentation | | :- | :- | :- | | `transform-data` | Transform and reshape data | [Transform Data](/reference/workspace-elements/flows/control-nodes#transform-data) | | `filter` | Filter which records continue through the flow | [Filter](/reference/workspace-elements/flows/control-nodes#filter) | | `for-each-v2` | Execute nodes for each item in a list | [For Each](/reference/workspace-elements/flows/control-nodes#for-each) |
## Inputs and Outputs When a flow starts, the trigger node receives an initial input. This could be: * Data from an API request (API Trigger) * Data from an external app event (Data Record Created Trigger) * Empty object for scheduled triggers (Schedule Trigger) * Data from an internal app event (Internal Event Trigger) Each node produces an output after executing. This output is added to the input of all downstream nodes under the node's key. For example, if a node with key `transform` produces output `{firstName: "John", lastName: "Doe"}`, the downstream nodes will receive: ```json theme={null} { "trigger-key": { /* trigger output */ }, "transform": { "firstName": "John", "lastName": "Doe" } } ``` These outputs are available for subsequent nodes as `input` variable. ## Variables You can use variables in the node configuration. Here are the available variables: * `input` - Initial flow input + outputs of all upstream nodes * `flowInstance` - data of the current flow. * `flowRun` - data of the current flow run. * `integration` - data of the current integration * `connection` - data of the current connection * `user` - data of the current user * `parameters` - parameters of the current flow You can reference any upstream node's output using the `$var` syntax: ```yaml theme={null} config: output: currentIntegrationId: $var: integration.id previousNodeOutput: $var: input.previous-node ``` ## Using Flows You can only run a flow created for a specific connection (having connectionId field). It can be either flow created for a specific connection only or an integration-level or universal flow instantiated for a specific connection. If your flow has an API trigger, you can run it via API or SDK. Otherwise, a flow will be executed automatically when the trigger conditions are met. See full API reference here: [Flows API Reference](https://.integration.app/update/reference/workspace-elements/flows). Each time a flow runs, it creates a [Flow Run](/docs/managing-membrane/monitoring-troubleshooting/logs/flow-runs) record. ## API Operations | Operation | Method | Endpoint | Description | | - | - | - | - | | [List all flows](/api-reference/flows/list-flows) | GET | `/flows` | Retrieve all workspace flows | | [Get flow](/api-reference/flows/get-flow-by-selector) | GET | `/flows/{selector}` | Get specific flow details | | [Create a new flow](/api-reference/flows/create-a-new-flow) | POST | `/flows` | Create a new workspace flow | | [Replace flow](/api-reference/flows/replace-flow-completely) | PUT | `/flows/{selector}` | Replace flow configuration | | [Patch flow](/api-reference/flows/update-flow-partially) | PATCH | `/flows/{selector}` | Update flow partially | | [Clone flow](/api-reference/flows/clone-flow) | POST | `/flows/{selector}/clone` | Clone an existing flow | | [Reset flow](/api-reference/flows/reset-flow) | POST | `/flows/{selector}/reset` | Reset flow to default state | | [Export flow](/api-reference/flows/export-flow-flat-interface) | GET | `/flows/{selector}/export` | Export flow configuration | | [Get flow dependencies](/api-reference/flows/get-dependencies-of-flow-flat-interface) | GET | `/flows/{selector}/dependencies` | Get flow dependencies | | [Restore flow](/api-reference/flows/restore-flow-flat-interface) | POST | `/flows/{selector}/restore` | Restore archived flow | | [Refresh flows](/api-reference/flows/refresh-flow) | POST | `/flows/refresh` | Refresh flow definitions | | [Archive flow](/api-reference/flows/archive-flow) | DELETE | `/flows/{selector}` | Archive a flow | # Control Nodes Source: https://docs.getmembrane.com/reference/workspace-elements/flows/control-nodes Control nodes manage the flow of execution, transform data, and implement conditional logic. They help you build complex workflows with branching, filtering, and iteration.
## Transform Data **Type:** `transform-data` The Transform Data node transforms input into a new data structure. This is one of the most commonly used nodes, essential for reshaping data between different formats. ```yaml theme={null} transform: type: transform-data name: Format Contact Data config: output: fullName: $eval: $concat: - $var: input.trigger.fields.firstName - ' ' - $var: input.trigger.fields.lastName email: $var: input.trigger.fields.email createdAt: $eval: $now: {} metadata: source: external-app syncedAt: $eval: $now: {} ``` The `output` configuration defines the structure of the transformed data. You can use variables (`$var`), expressions (`$eval`), or static values. **Output:** Returns the transformed object as specified in the `output` configuration: ```javascript theme={null} { fullName: 'John Doe', email: 'john@example.com', createdAt: '2024-01-15T10:30:00Z', metadata: { source: 'external-app', syncedAt: '2024-01-15T10:30:00Z' } } ```
## Filter **Type:** `filter` The Filter node conditionally allows data to continue through the flow. Only inputs that match the filter criteria are passed to downstream nodes. ```yaml theme={null} filter: type: filter name: Only Active Contacts config: filter: $eval: $var: input.findContact.fields.status $eq: active ``` **Configuration options:** * **`filter`** – Filter expression using evaluation syntax (supports `$eq`, `$gt`, `$and`, `$or`, etc.) **Output:** The filter node passes through the input unchanged if it matches the filter. If the input doesn't match, no output is produced and the flow stops for that input.
## For Each **Type:** `for-each-v2` The For Each node executes a subset of flow nodes for each item in a list, then aggregates their outputs. This is essential for processing arrays of data. ```yaml theme={null} forEach: type: for-each-v2 name: Process Each Contact config: items: $var: input.listContacts rootNodeKey: processContact links: - key: summary processContact: type: transform-data name: Transform Contact config: output: id: $var: input.forEach.item.id fullName: $eval: $concat: - $var: input.forEach.item.fields.firstName - ' ' - $var: input.forEach.item.fields.lastName links: - key: createInCRM createInCRM: type: create-data-record name: Create in CRM config: dataSource: collectionKey: contacts fieldMapping: defaultValue: name: $var: input.processContact.fullName summary: type: transform-data name: Create Summary config: output: processed: $var: input.forEach allCreatedContacts: $var: input.forEach.createInCRM ``` **Configuration options:** * **`items`** – Array of items to iterate over (usually from a previous node's output) * **`rootNodeKey`** – Key of the first node inside the For Each loop **How it works:** 1. The For Each node receives a list of items 2. For each item, it executes the nodes inside the loop (starting from `rootNodeKey`) 3. Inside the loop, the current item is available as `input.forEach.item` (where `forEach` is the key of your for-each node) 4. All nodes inside the loop run for each item 5. After all items are processed, outputs are aggregated into a list **Accessing the current item:** Inside the For Each loop, access the current item: ```yaml theme={null} $var: input.forEach.item $var: input.forEach.item.id $var: input.forEach.item.fields.email ``` **Output structure:** The For Each node outputs an object with keys matching the nodes inside the loop, and values being arrays of their outputs: ```javascript theme={null} { processContact: [ { id: '1', fullName: 'John Doe' }, { id: '2', fullName: 'Jane Smith' } ], createInCRM: [ { id: 'crm-1', name: 'John Doe' }, { id: 'crm-2', name: 'Jane Smith' } ] } ``` # Flow UI Source: https://docs.getmembrane.com/reference/workspace-elements/flows/flow-ui To let a user configure a Flow Instance, call the `openConfiguration` method: ```javascript theme={null} await membrane.connection('hubspot').flow('{FLOW_KEY}').openConfiguration() ```
### Flow Instance editor To edit a Flow Instance, call the `openEditor` method: ```javascript theme={null} await membrane.flowInstance('{FLOW_INSTANCE_ID}').openEditor() ```
Alternatively, you can embed the Flow Instance editor directly into a specific element: ```javascript theme={null} function FlowBuilderEmbedding() { const targetId = 'flow-builder-emdedding' const membrane = useIntegrationApp() const targetRef = useRef < HTMLDivElement > null useEffect(() => { void membrane .flowInstance({ flowKey: parameters.FLOW_KEY, integrationKey: parameters.INTEGRATION_KEY, autoCreate: true, }) .embedEditor({ mountTargetSelector: `[data-container-id="${targetId}"]`, }) }, [parameters.FLOW_KEY, parameters.INTEGRATION_KEY, membrane]) return } ```
## See Also
The parameters must match the Parameters Schema you configured for the flow. # Custom Flow UI Source: https://docs.getmembrane.com/reference/workspace-elements/flows/flow-ui/custom-flow-ui To build custom white-label UI for a flow, use one of the following articles:
## Data Record Operations These nodes operate on data records in external applications. Most of them map directly to function types. | Node Type | Description | Function Type | | :- | :- | :- | | `list-data-records` | List all records from a data collection | [List Data Records](/docs/references/functions/function-types/list-data-records) | | `find-data-record-by-id` | Find a single record by its ID | [Find Data Record By ID](/docs/references/functions/function-types/find-data-record-by-id) | | `search-data-records` | Search for records using a query string | [Search Data Record](/docs/references/functions/function-types/search-data-record) | | `lookup-data-record` | Look up a record by field values | [Match Data Record](/docs/references/functions/function-types/match-data-record) | | `create-data-record` | Create a new data record | [Create Data Record](/docs/references/functions/function-types/create-data-record) | | `update-data-record` | Update an existing data record | [Update Data Record](/docs/references/functions/function-types/update-data-record) | | `delete-data-record` | Delete a data record | [Delete Data Record](/docs/references/functions/function-types/delete-data-record) |
## Find or Create Data Record **Type:** `find-or-create-data-record` Attempts to find a record by specified criteria. If no record is found, creates a new one. This is useful for upserting data. ```yaml theme={null} findOrCreate: type: find-or-create-data-record name: Find or Create Contact config: dataSource: collectionKey: contacts lookupFields: email: $var: input.trigger.email createData: firstName: $var: input.trigger.firstName lastName: $var: input.trigger.lastName email: $var: input.trigger.email fieldMapping: key: contact-mapping ``` **Configuration options:** * **`dataSource`** – Specifies which [Data Source](/reference/workspace-elements/data-sources) to use * **`lookupFields`** – Fields to match when searching for existing records * **`createData`** – Data to use when creating a new record * **`fieldMapping`** – [Field Mapping](/reference/workspace-elements/field-mappings) for the operation **Output:** Returns the found or newly created data record: ```javascript theme={null} { id: 'contact-456', name: 'Jane Smith', fields: { firstName: 'Jane', lastName: 'Smith', email: 'jane@example.com' }, created: false // true if record was created, false if found } ```
## Create Data Link **Type:** `create-data-link` Creates a [Data Link](/reference/workspace-elements/data-links) between an object in your app and an object in an external app. ```yaml theme={null} createLink: type: create-data-link name: Link Contact config: dataLinkTable: contact-links internalId: $var: input.trigger.internalContactId externalId: $var: input.createRecord.id direction: both ``` **Configuration options:** * **`dataLinkTable`** – The Data Link table to use (must be created first) * **`internalId`** – ID of the object in your app * **`externalId`** – ID of the object in the external app * **`direction`** – Link direction: `export` (internal → external), `import` (external → internal), or `both` If a link already exists, it will be updated. **Output:** Returns the created or updated data link: ```javascript theme={null} { id: 'link-789', internalId: 'internal-contact-123', externalId: 'external-contact-456', direction: 'both' } ```
## Find Data Link **Type:** `find-data-link` Finds a [Data Link](/reference/workspace-elements/data-links) to get the corresponding object ID on the opposite side. ```yaml theme={null} findLink: type: find-data-link name: Find Linked Contact config: dataLinkTable: contact-links internalId: $var: input.trigger.internalContactId ``` **Configuration options:** * **`dataLinkTable`** – The Data Link table to search * **`internalId`** – ID to look up (can be internal or external depending on direction) **Output:** Returns the ID of the matching record on the opposite side, or null if no link is found: ```javascript theme={null} { externalId: 'external-contact-456' } // or null if not found ```
## Delete Data Link **Type:** `delete-data-link` Deletes an existing [Data Link](/reference/workspace-elements/data-links). ```yaml theme={null} deleteLink: type: delete-data-link name: Unlink Contact config: dataLinkTable: contact-links internalId: $var: input.trigger.internalContactId ``` **Configuration options:** * **`dataLinkTable`** – The Data Link table containing the link * **`internalId`** – ID of the linked object **Output:** Returns confirmation of deletion: ```javascript theme={null} { success: true, deletedLinkId: 'link-789' } ```
## HTTP Request Operations These nodes make HTTP requests to APIs and external services. | Node Type | Description | Function Type | | :- | :- | :- | | `api-request-to-external-app` | Make authenticated API requests to external apps | [API Request to External App](/docs/references/functions/function-types/api-request-to-external-app) | | `api-request-to-your-app` | Make API requests to your internal API | [API Request to Your App](/docs/references/functions/function-types/api-request-to-your-app) | | `custom-http-request` | Make arbitrary HTTP requests to any endpoint | [HTTP Request](/docs/references/functions/function-types/http-request) |
## Code Execution These nodes execute code and run predefined actions. | Node Type | Description | Function Type | | :- | :- | :- | | `run-javascript` | Execute custom JavaScript or TypeScript code | [JavaScript](/docs/references/functions/function-types/javascript) | | `run-action` | Execute a predefined action | [Run Action](/docs/references/functions/function-types/run-action) |
## Integration Specific Operation **Type:** `integration-specific-operation` Executes operations that are specific to a particular integration. These are pre-built operations provided by connectors. ```yaml theme={null} specialOp: type: integration-specific-operation name: Send Email config: operationKey: send-email parameters: to: $var: input.findContact.fields.email subject: Welcome! body: $var: input.transform.emailBody ``` **Configuration options:** * **`operationKey`** – Key of the integration-specific operation * **`parameters`** – Parameters required by the operation The available operations and their parameters depend on the specific connector being used. Refer to connector documentation for details. **Output:** Returns the result of the operation. Structure varies by operation: ```javascript theme={null} { success: true, messageId: 'msg-123', // ... other operation-specific fields } ``` # Trigger Nodes Source: https://docs.getmembrane.com/reference/workspace-elements/flows/trigger-nodes Trigger nodes are special nodes that start flow execution. Every flow must have at least one trigger. A flow can have multiple triggers if you want to reuse the same integration logic in different scenarios.
## API Trigger **Type:** `api-trigger` The API Trigger allows you to launch a Flow Instance with optional input using your application's API or SDK. ```yaml theme={null} trigger: type: api-trigger name: Manual Sync Trigger config: inputSchema: type: object properties: recordId: type: string syncAll: type: boolean ``` **Configuration options:** * **`inputSchema`** – Optional schema that will be validated when the flow is triggered **Output:** The output contains the input provided when triggering the flow: ```javascript theme={null} { recordId: '12345', syncAll: false } ```
## Schedule Trigger **Type:** `schedule-trigger` The Schedule Trigger runs a flow at regular intervals as long as the Flow Instance is enabled. ```yaml theme={null} trigger: type: schedule-trigger name: Hourly Sync config: intervalMinutes: 60 ``` **Configuration options:** * **`intervalMinutes`** – How often the flow should run (5 = every 5 minutes, 60 = hourly, 1440 = daily) **Output:** The output contains timing information: ```javascript theme={null} { triggeredAt: '2024-01-15T10:30:00Z' } ```
## Internal Event Trigger **Type:** `app-event-trigger` The Internal Event Trigger runs a flow when a specific event occurs in your application. Before using this trigger, you need to create an [Internal Event](/docs/managing-membrane/monitoring-troubleshooting/logs/internal-events). ```yaml theme={null} trigger: type: app-event-trigger name: Order Created Event config: appEventKey: order-created filter: $eval: $var: $.payload.amount $gt: 1000 ``` **Configuration options:** * **`appEventKey`** – Key of the internal event to listen to * **`filter`** – Optional filter to conditionally trigger the flow based on event data **Output:** The output contains the event payload: ```javascript theme={null} { payload: { orderId: '12345', amount: 1500, customer: 'customer-id' } } ```
## Data Record Created Trigger **Type:** `data-record-created-trigger` This trigger launches a flow when a new data record is created in a selected Data Source. ```yaml theme={null} trigger: type: data-record-created-trigger name: New Contact Created config: dataSource: collectionKey: contacts fieldMapping: key: contact-mapping defaultValue: firstName: $var: $.rawFields.first_name lastName: $var: $.rawFields.last_name email: $var: $.rawFields.email ``` **Configuration options:** * **`dataSource`** – Specifies which [Data Source](/reference/workspace-elements/data-sources) collection to monitor * **`fieldMapping`** – Optional [Field Mapping](/reference/workspace-elements/field-mappings) to transform data from the external app to your app's format **Output:** The output contains information about the created record: ```javascript theme={null} { id: 'contact-123', name: 'John Doe', url: 'https://app.com/contacts/123', fields: { firstName: 'John', lastName: 'Doe', email: 'john@example.com' }, rawFields: { first_name: 'John', last_name: 'Doe', email: 'john@example.com' } } ```
## Data Record Updated Trigger **Type:** `data-record-updated-trigger` This trigger launches a flow when an existing data record is updated in a selected Data Source. ```yaml theme={null} trigger: type: data-record-updated-trigger name: Contact Updated config: dataSource: collectionKey: contacts fieldMapping: key: contact-mapping ``` **Configuration options:** * **`dataSource`** – Specifies which [Data Source](/reference/workspace-elements/data-sources) collection to monitor * **`fieldMapping`** – Optional [Field Mapping](/reference/workspace-elements/field-mappings) to transform updated data **Output:** The output contains the updated record data in the same format as Data Record Created Trigger.
## Data Record Deleted Trigger **Type:** `data-record-deleted-trigger` This trigger launches a flow when a data record is deleted in a selected Data Source. ```yaml theme={null} trigger: type: data-record-deleted-trigger name: Contact Deleted config: dataSource: collectionKey: contacts fieldMapping: key: contact-mapping ``` **Configuration options:** * **`dataSource`** – Specifies which [Data Source](/reference/workspace-elements/data-sources) collection to monitor * **`fieldMapping`** – Optional [Field Mapping](/reference/workspace-elements/field-mappings) to transform data about the deleted record **Output:** The output contains information about the deleted record. Note that some external apps may only provide the record ID. ```javascript theme={null} { id: 'contact-123', name: 'John Doe' } ```
## Connector Event Trigger **Type:** `connector-event-trigger` The Connector Event Trigger launches flows in response to connector-specific events. ```yaml theme={null} trigger: type: connector-event-trigger name: Custom Webhook Event config: eventKey: custom-event filter: $eval: $var: $.payload.status $eq: completed ``` **Configuration options:** * **`eventKey`** – Key of the event to trigger on * **`filter`** – Optional filter to conditionally trigger the flow **Output:** The output structure depends on the specific connector and event type. Refer to the connector's documentation for details. # Incoming Webhooks Source: https://docs.getmembrane.com/reference/workspace-elements/incoming-webhooks # Integrations Source: https://docs.getmembrane.com/reference/workspace-elements/integrations Integration represents a relationship between your product and a given external app. ## Integration Definition Integration looks like this: ```yaml theme={null} name: Github key: github logoUri: https://static.integration.app/connectors/github/logo.png appUuid: c04f4af3-1704-4693-86a4-9af453205335 connectorId: 62471fad996d5c297ae43f5f connectorVersion: 2.3.1 authOptions: - title: API Key description: Connect using one of the Github API key types type: client-credentials - title: OAuth description: Connect in one click by approving this app's access type: oauth2 ``` In this definition: * `logoUri` - URL of the publicly available image with the integration logo. * `appUuid` - uuid of the [External App](/reference/workspace-elements/external-apps) this integration is related to. * `connectorId` - id of the [Connector](/reference/workspace-elements/connectors) this integration uses. * `connectorVersion` - a published version of the connector. If empty, development (unpublished) version of the connector is used. * `authOptions` (read-only) - list of available authentication options based on the connector and integration parameters. The format of auth options matches the auth config from the [Connector](/reference/workspace-elements/connectors) definition with all the [Formulas](/docs/references/formulas) resolved (if there were any). ## Connector Parameters If the connector used by an integration has [parameters](/reference/workspace-elements/connectors#connector-parameters) (for example `clientId` and `clientSecret` for OAuth), you can store their values on the integration level. For security reasons, parameters are not saved as a part of the integration definition and are not returned in the response by default. Read them by fetching the integration with `?includeSecrets=true` (the response includes both `parameters` and `optionsConfig`), and write them with [Patch integration](/api-reference/integrations/update-integration-partially). Where you put them depends on the connector's auth options: * **Single auth option** — store the values at the top level, under `parameters`: ```json theme={null} { "parameters": { "clientId": "...", "clientSecret": "..." } } ``` * **[Multiple auth options](/reference/workspace-elements/connectors#connector-options)** — store each option's values under `optionsConfig.
To understand the state of the connection for a given integration, look at the following fields to display in the UI: | Field | Description | | - | - | | `connection` | If this integration has a connection established for the current user, this field will be non-empty | | `connection.disconnected` | If a connection is disconnected and requires user to re-connect, this flag will be set to true. | ## Re-connect and Disconnect You can use the following code to re-connect an integration if it was disconnected or if the user wants to re-connect for any other reason: ```javascript theme={null} await membrane.integration('hubspot').openNewConnection() ```
Or a custom version of this UI: [Custom Connection UI](/docs/ways-to-use-membrane/embedded-ui/connection-ui/custom-connection-ui). You can disconnect the integration using the following code: ```javascript theme={null} await membrane.connection('hubspot').archive() ```
## Manage Tenant-level Elements To know which [Flows](/reference/workspace-elements/flows), [Actions](/docs/how-membrane-works/actions), [Data Sources](/reference/workspace-elements/data-sources), or [Field Mappings](/reference/workspace-elements/field-mappings) are configured for the current integration, you can get their list this way: ```javascript theme={null} const { items: flowInstances } = await membrane.connection('hubspot').flows.list() const { items: actionInstances } = await membrane.connection('hubspot').actions.list() const { items: dataSourceInstances } = await membrane.connection('hubspot').dataSources.list() const { items: fieldMappingInstances } = await membrane.connection('hubspot').fieldMappings.list() ```
Then you can use the corresponding elements API and UI to manage them: | Element | API | UI | | - | - | - | | Flow | [Flows API](/reference/workspace-elements/flows) | [Flows UI](/reference/workspace-elements/flows/flow-ui/custom-flow-ui) | | Data Source | [Data Sources API](/reference/workspace-elements/data-sources/data-source-instances) | [Data Sources UI](/reference/workspace-elements/data-sources/data-source-instances) | | Field Mapping | [Field Mappings API](/reference/workspace-elements/field-mappings/field-mapping-instances) | [Field Mappings UI](/reference/workspace-elements/field-mappings/field-mapping-instances) | # Custom Integrations Catalog UI Source: https://docs.getmembrane.com/reference/workspace-elements/integrations/integrations-catalog/custom-list-of-integrations # UI for Managing Connections *Display the list of integrations, connect and disconnect external apps, configure connections.* ## List Integrations Your integration experience likely starts with a list of integrations your user can enable. To get this list, use the following code: ```javascript theme={null} const { items: integrations } = await membrane.integrations.find() ``` Integrations that already have a Connection created will have a `connection` property.\ You can use it to indicate that the integration is already connected. You can manage the list of available integrations on the [Integrations](/reference/workspace-elements/connectors) page. ## List Connections If you want to list all the connections a user has created without listing all the available integrations, do this: ```javascript theme={null} const { items: connections } = await membrane.connections.find() ```
## Connect To connect a user's account in a specific third-party app, call this method: ```javascript theme={null} await membrane.integration('hubspot').openNewConnection() ```
Or if you want to create your own authentication UI, check out this guide: [Custom Connection UI](/docs/ways-to-use-membrane/embedded-ui/connection-ui/custom-connection-ui) ## Disconnect To disconnect a specific connection, call this method: ```javascript theme={null} await membrane.connection('hubspot').archive() ```
## Next Steps