Skip to main content
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). You can also create and manage them via the API — see Tenants API Reference.

​
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: 
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. 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.