Quick Start

Connect your software to external apps via Membrane

In this guide, we will create UI inside your product to connect external apps via Membrane. It will let your users create Connections that your product will use to interact with external apps.

Quick Start with AI

🚧

This is an experimental feature. AI coding agents are non-deterministic and change daily. Results may vary. If you don't get the outcome you expected, fall back to the manual process below.

Membrane is designed to be used with AI and by AI. The best way to get started quickly is to introduce your coding agent to Membrane and ask it to build integrations.

Here is how to do it:

  1. Copy Initial Context for AI into a new chat with your AI agent (Cursor, Claude Code, etc).
  2. Ask it "add UI for connecting external apps using Membrane".

This should be enough for the fully working UI to appear in your product. If this doesn't go well - see the steps below to help your agent find its way.

Quick Start without AI

1. Create Authentication Token

To interact with Membrane, you need to use an authentication token.

To generate it, you need Workspace Key and Workspace Secret. You can find them in your workspace settings.


import jwt from 'jsonwebtoken'
// Your workspace key and secret.
// You can find them on the Settings page.
const WORKSPACE_KEY = '<WORKSPACE_KEY>'
const WORKSPACE_SECRET = '<WORKSPACE_SECRET>'

const tokenData = {
  // Identifier of your customer (user, team, or organization).
  id: '{CUSTOMER_ID}',
  // Human-readable customer name.
  name: '{CUSTOMER_NAME}',
  // (optional) Any user fields you want to attach to your customer.
  fields: {
    userField: '<user field value>'
  }
}

const options = {
  issuer: WORKSPACE_KEY,
  // To prevent token from being used for too long
  expiresIn: 7200,
  // HS256 signing algorithm is used by default,
  // but we recommend to go with more secure option like HS512.
  algorithm: 'HS512'
}

const token = jwt.sign(tokenData, WORKSPACE_SECRET, options)
import datetime
import jwt

# Your workspace key and secret.
# You can find them on the Settings page.
WORKSPACE_KEY = "f88f52bc-57a9-47e3-93b3-843fa0dd5708"
WORKSPACE_SECRET = "2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66"

encoded_jwt = jwt.encode(
    {
      # ID of your customer in your system.
      # It will be used to identify customer in Integration.app
      "id": "{CUSTOMER_ID}",
      # Human-readable name (it will simplify troubleshooting)
      "name": "{CUSTOMER_NAME}",
      "iss": WORKSPACE_KEY,
      # Any customer fields you want to attach to your user.
      "fields": {
        "field1": "<field value>"
      }
      "exp": datetime.datetime.now() + datetime.timedelta(seconds=1440)
    }, WORKSPACE_SECRET, algorithm="HS256")
import (
    "time"
    "github.com/dgrijalva/jwt-go"
)

var WORKSPACE_KEY = "f88f52bc-57a9-47e3-93b3-843fa0dd5708"
var WORKSPACE_SECRET = "2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66"

var SigningKey = []byte(WORKSPACE_SECRET)


claims := jwt.MapClaims{
    // Identifier of your customer (user, team, or organization).
    "id" : "{CUSTOMER_ID}",
    // Human-readable customer name.
    "name": "{CUSTOMER_NAME}",
    // To prevent token from being used for too long
    "exp": time.Now().Add(time.Hour * 24).Unix(),
    "iss": WORKSPACE_KEY,
    }

token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
tokenString, err := token.SignedString(SigningKey)
require 'jwt'

WORKSPACE_SECRET = '2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66'
WORKSPACE_KEY = 'f88f52bc-57a9-47e3-93b3-843fa0dd5708'

payload = {
  id: '{CUSTOMER_ID}',
  name: '{CUSTOMER_NAME}',
  iss: WORKSPACE_KEY,
  exp: Time.now.to_i + 60 * 60 * 6, # Expiration time (6 hours from now)
}

token = JWT.encode(payload, WORKSPACE_SECRET, 'HS256')
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

import javax.crypto.spec.SecretKeySpec;
import java.time.temporal.ChronoUnit;
import java.util.Date;


String workspaceKey = "f88f52bc-57a9-47e3-93b3-843fa0dd5708";
String workspaceSecret = "2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66";

String jwtToken = Jwts.builder()
        .claim("id", "{CUSTOMER_ID}") // Identifier of user or organization.
        .claim("name", "{CUSTOMER_NAME}") // Human-readable name (it will simplify troubleshooting)
        // .claim("fields", <user fields value>) (optional) Any user fields you want to attach to your user.
        .setExpiration(Date.from(new Date().toInstant().plus(14400, ChronoUnit.SECONDS))) // To prevent token from being used for too long
        .setIssuer(workspaceKey)
        .signWith(new SecretKeySpec(workspaceSecret.getBytes(), SignatureAlgorithm.HS256.getJcaName()), SignatureAlgorithm.HS256)
        .setHeaderParam("typ", "JWT")
        .compact();
use FirebaseJWTJWT;

// Your workspace key and secret.
// You can find them on the Settings page.
$secret = '2246bd2dcd556be028b6b336bee3adf9851a6f548717a0cd25904fb781f32f66';
$key = 'f88f52bc-57a9-47e3-93b3-843fa0dd5708';

$payload = [
    'id' => "{CUSTOMER_ID}",  // ID of your customer in your system. It will be used to identify customer in Integration.app
    'name' => "{CUSTOMER_NAME}", // Human-readable customer name (it will simplify troubleshooting)
    'iss' => $key,
    'exp' => time() + 60 * 60 * 24 * 60, // To prevent token from being used for too long
];
$token = JWT::encode($payload, $secret, 'HS256');

This token includes CUSTOMER_ID and CUSTOMER_NAME which are unique id and name of the current customer of your product. It can be a current user, organization, team, or any other entity you want to associate integrations with.

📘

Always generate authentication token on your backend and never on the front-end. The workspace secret used to generate the token cannot be shared.

See more details on authentication tokens here: Authentication.

2. Create a Connection

To connect an external app, you need to display a Connection UI in your front-end.

2.1. Set up a front-end SDK

To connect your customer accounts and use integrations from your front-end, you need to install an SDK. You can choose from one of these options:

2.2. Display a Connection UI

To start interacting with external apps on behalf of your customer, you need to create a Connection.

The simplest way to display a connection UI is to use .open() method of the Membrane SDK:

integrationApp.open()

This pre-built UI is a good place to start. To build your own fully custom connection UI, check these guides:

2.3. Add and connect an External App

To make apps appear in this UI, you need to add them to your workspace.

See External Apps for details on how to do it. After you add an app, it will appear in your connection UI. After you click on it in the connection UI and go through the authentication process, a Connection object will be created.

Congratulations! Your app can now interact with external apps through Membrane.

Next Steps