Workspace Provisioning - Membrane Docs

Programmatically create and configure workspaces for your organization. This is useful for multi-tenant SaaS platforms that need to provision isolated integration environments for their own customers. These endpoints require organization-level authentication (platform user tokens), not workspace-level tokens.

Key Concepts

Organizations

An Organization (Org) is the top-level entity that groups your team and workspaces. Org members share billing, authentication, and access controls. Organizations exist on the Hub — the central management layer.

Org Workspaces

An Org Workspace represents a workspace as seen from the organization level. It stores the workspace’s name, key, secret, and org membership. Org workspaces also exist on the Hub and are used for provisioning, access control, and credential management.

Workspaces

A Workspace is the runtime environment where integrations, connections, and tenant data live. Workspaces store the actual configuration — settings, webhook URIs, public keys, and tenant data. In a multi-instance deployment, each workspace runs on a specific Instance.

Architecture

┌─────────────────────────────────────────────────┐
│                   Hub                            │
│                                                  │
│  ┌───────────┐                                   │
│  │    Org     │                                   │
│  └─────┬─────┘                                   │
│        │ has many                                 │
│  ┌─────┴──────────────┐                           │
│  │                    │                           │
│  ▼                    ▼                           │
│ ┌──────────────┐   ┌──────────────┐               │
│ │ OrgWorkspace │   │ OrgWorkspace │               │
│ │ (Production) │   │ (Development)│               │
│ └──────┬───────┘   └──────┬───────┘               │
│        │                  │                       │
└────────┼──────────────────┼───────────────────────┘
         │ maps to          │ maps to
┌────────┼──────────┐  ┌───┼────────────────┐
│  Instance A       │  │  Instance B        │
│  ┌────▼────────┐  │  │  ┌────▼────────┐   │
│  │  Workspace  │  │  │  │  Workspace  │   │
│  │ (settings,  │  │  │  │ (settings,  │   │
│  │  tenants,   │  │  │  │  tenants,   │   │
│  │  data)      │  │  │  │  data)      │   │
│  └─────────────┘  │  │  └─────────────┘   │
└───────────────────┘  └────────────────────┘

In a single-instance (cloud) setup, the hub and instance are the same server, so org workspaces and workspaces are always co-located. The separation matters in multi-instance (self-hosted) deployments, where:

The Hub manages organizations, org workspaces, user access, and credential rotation centrally.
Each Instance runs one or more workspaces with their integration data, connections, and tenant state.
The Management API operates on the Hub and routes workspace-level configuration changes to the appropriate instance.

Typical Workflow

Create a workspace via POST /org-workspaces with a name and org ID.
Configure it via PATCH /org-workspaces/{id} — set webhook URIs, public keys, settings, etc.
Generate an access token via POST /org-workspaces/{id}/access-token to authenticate API calls scoped to that workspace.
Rotate secrets via POST /org-workspaces/{id}/rotate-secret when needed.
Archive/restore workspaces as your customers come and go.

​Key Concepts

​Organizations

​Org Workspaces

​Workspaces

​Architecture

​Typical Workflow