> ## Documentation Index
> Fetch the complete documentation index at: https://docs.membrane.agency/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Provisioning

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

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