Organizations & Workspaces

Understand the resource hierarchy for multi-tenant integration management.

Organizations & Workspaces

Weavz uses a two-level hierarchy to organize resources: organizations at the top and workspaces within them.

Organizations

An organization is the top-level container for all your Weavz resources. Every connection, MCP server, trigger, and API key belongs to an organization.

When you sign up for Weavz, you create your first organization automatically. You can create additional organizations to separate distinct products or clients.

What belongs to an organization

API keys
Workspaces
End users (scoped to workspaces)
Connections
MCP servers
Triggers
Members
Billing and usage

API keys are scoped to your organization by default. You can also create workspace-scoped keys that restrict access to specific workspaces — see API Keys guide for details. Treat API keys like server-side secrets.

Workspaces

Workspaces are configured integration containers — not empty scoping buckets. Each workspace declares which integrations it uses, how connections are resolved for each, and which actions are available. This makes workspaces the central configuration unit for multi-tenant and multi-environment setups.

Common patterns:

By environment — production, staging, development
By application — mobile-app, web-dashboard, internal-tools
By customer — when building a multi-tenant product, create a workspace per end-customer

Workspace integrations

After creating a workspace, you configure it by adding workspace integrations — each one declares:

Which integration to use (e.g., slack, github)
A connection strategy (fixed, per_user, or per_user_with_fallback)
An optional connection (the fixed or fallback connection)
An optional alias for disambiguation when the same integration appears multiple times
An optional allowed actions list to restrict which actions are available

bash

# Create the workspace
curl -X POST https://api.weavz.io/api/v1/workspaces \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "slug": "production"}'
 
# Add Slack with a fixed connection
curl -X POST https://api.weavz.io/api/v1/workspaces/{workspaceId}/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "connectionStrategy": "fixed",
    "connectionId": "conn_slack_prod"
  }'
 
# Add Gmail where each user provides their own connection
curl -X POST https://api.weavz.io/api/v1/workspaces/{workspaceId}/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "gmail",
    "connectionStrategy": "per_user"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
// Create the workspace
const { workspace } = await client.workspaces.create({
  name: 'Production',
  slug: 'production',
})
 
// Add Slack with a fixed connection
await client.workspaces.addIntegration(workspace.id, {
  integrationName: 'slack',
  connectionStrategy: 'fixed',
  connectionId: 'conn_slack_prod',
})
 
// Add Gmail where each user provides their own connection
await client.workspaces.addIntegration(workspace.id, {
  integrationName: 'gmail',
  connectionStrategy: 'per_user',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
# Create the workspace
result = client.workspaces.create(name="Production", slug="production")
workspace = result["workspace"]
 
# Add Slack with a fixed connection
client.workspaces.add_integration(workspace["id"],
    integration_name="slack",
    connection_strategy="fixed",
    connection_id="conn_slack_prod",
)
 
# Add Gmail where each user provides their own connection
client.workspaces.add_integration(workspace["id"],
    integration_name="gmail",
    connection_strategy="per_user",
)

typescript

// Create the workspace
const wsRes = await fetch('https://api.weavz.io/api/v1/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'Production', slug: 'production' }),
})
const { workspace } = await wsRes.json()
 
// Add Slack with a fixed connection
await fetch(`https://api.weavz.io/api/v1/workspaces/${workspace.id}/integrations`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    connectionStrategy: 'fixed',
    connectionId: 'conn_slack_prod',
  }),
})
 
// Add Gmail where each user provides their own connection
await fetch(`https://api.weavz.io/api/v1/workspaces/${workspace.id}/integrations`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'gmail',
    connectionStrategy: 'per_user',
  }),
})

python

import httpx
 
headers = {"Authorization": "Bearer wvz_your_api_key"}
 
# Create the workspace
res = httpx.post(
    "https://api.weavz.io/api/v1/workspaces",
    headers=headers,
    json={"name": "Production", "slug": "production"},
)
workspace = res.json()["workspace"]
 
# Add Slack with a fixed connection
httpx.post(
    f"https://api.weavz.io/api/v1/workspaces/{workspace['id']}/integrations",
    headers=headers,
    json={
        "integrationName": "slack",
        "connectionStrategy": "fixed",
        "connectionId": "conn_slack_prod",
    },
)
 
# Add Gmail where each user provides their own connection
httpx.post(
    f"https://api.weavz.io/api/v1/workspaces/{workspace['id']}/integrations",
    headers=headers,
    json={
        "integrationName": "gmail",
        "connectionStrategy": "per_user",
    },
)

Connection strategies

Strategy	Description
`fixed`	A single connection is always used. Best for shared service accounts.
`per_user`	Each user must provide their own connection. No fallback.
`per_user_with_fallback`	Users can provide their own connection, with a default fallback.

See the Workspace Integrations API for full endpoint documentation.

End users

Workspaces contain end users — the people who use your product. Each end user can own connections to third-party integrations, enabling per-user credential management.

graph TD
    Org[Organization: My SaaS Product]
    Org --> WS[Workspace: Production]
    WS --> Int[Integration: slack - per_user]
    WS --> Alice[End User: alice]
    WS --> Bob[End User: bob]
    WS --> Charlie[End User: charlie]
    Alice --> AC[Alice's Slack Connection]
    Bob --> BC[Bob's Slack Connection]
    Charlie -.- NC[no connections yet]
    style NC stroke-dasharray: 5 5

End users are created via the API or auto-created when a connection is established through the hosted connect portal. See Managing End Users for a step-by-step guide.

Resource isolation

When you create resources within a workspace, they are scoped to that workspace:

Workspace integrations define which integrations and connections are available
End users and their connections are scoped to the workspace
Connections created in a workspace are only visible within that workspace
Triggers can be scoped to a workspace
MCP servers can be synced from a workspace's integration configuration

This isolation makes workspaces ideal for multi-tenant scenarios where different end users or environments should not share credentials.

Creating a workspace

bash

curl -X POST https://api.weavz.io/api/v1/workspaces \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "slug": "production"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { workspace } = await client.workspaces.create({
  name: 'Production',
  slug: 'production',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.workspaces.create(name="Production", slug="production")
workspace = result["workspace"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/workspaces', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Production',
    slug: 'production',
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/workspaces",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={"name": "Production", "slug": "production"},
)
data = res.json()

MCP server auto-sync

When you add, update, or remove integrations in a workspace, any MCP servers linked to that workspace automatically reflect the changes. There is no need to manually trigger a sync -- MCP server tools stay in sync with the workspace's integration configuration at all times.

Members

Organizations support role-based access control with three roles:

Role	Permissions
Owner	Full access, manage billing, delete organization
Admin	Manage members, connections, integrations, and settings
Member	Create and manage their own connections, view shared resources

Inviting members

bash

curl -X POST https://api.weavz.io/api/v1/members/invite \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "role": "ADMIN"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { member } = await client.members.create({
  userId: 'user_abc123',
  role: 'ADMIN',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.members.create(user_id="user_abc123", role="ADMIN")
member = result["member"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/members/invite', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    role: 'ADMIN',
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/members/invite",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={"email": "[email protected]", "role": "ADMIN"},
)
data = res.json()

Multi-Tenancy Patterns

Single organization, multiple workspaces

Best for SaaS products where you manage integrations on behalf of your customers. Each workspace is a configured integration container:

graph TD
    Org[Organization: My SaaS Product]
    Org --> A[Workspace: Customer A]
    Org --> B[Workspace: Customer B]
    Org --> C[Workspace: Internal]
    A --> A1[slack - fixed]
    A --> A2[github - fixed]
    B --> B1[slack - fixed]
    B --> B2[google-sheets - per_user]
    C --> C1[slack - fixed]

SaaS with per-customer credentials

Create a workspace per customer with fixed connection strategy:

For each customer:
1. Create a workspace
2. Create a connection with the customer's OAuth2 credentials
3. Add a workspace integration with strategy "fixed" pointing to that connection
4. All actions in that workspace context use the customer's credentials

SaaS with end-user OAuth2

Use per_user strategy and externalId to let each end-user connect their own accounts:

1. Create a workspace integration with strategy "per_user"
2. When an end-user connects, create a connection with externalId = their user ID
3. When executing actions, pass externalId to resolve their connection

Hybrid approach

Use per_user_with_fallback for optional personalization:

1. Create a default connection (e.g., your company's Slack bot)
2. Add a workspace integration with strategy "per_user_with_fallback" pointing to the default
3. Users who connect their own Slack get personalized access
4. Users who don't still get functionality via the default bot

External IDs

For fine-grained multi-tenancy, use externalId on connections. This lets you associate a connection with a specific end-user in your system without creating a separate workspace per user.

bash

curl -X POST https://api.weavz.io/api/v1/connections \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PLATFORM_OAUTH2",
    "integrationName": "slack",
    "externalId": "user_12345",
    "displayName": "User 12345 Slack",
    "accessToken": "xoxb-..."
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { connection } = await client.connections.create({
  type: 'PLATFORM_OAUTH2',
  integrationName: 'slack',
  externalId: 'user_12345',
  displayName: 'User 12345 Slack',
  accessToken: 'xoxb-...',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.connections.create(
    type="PLATFORM_OAUTH2",
    integration_name="slack",
    external_id="user_12345",
    display_name="User 12345 Slack",
    access_token="xoxb-...",
)
connection = result["connection"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/connections', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'PLATFORM_OAUTH2',
    integrationName: 'slack',
    externalId: 'user_12345',
    displayName: 'User 12345 Slack',
    accessToken: 'xoxb-...',
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/connections",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "type": "PLATFORM_OAUTH2",
        "integrationName": "slack",
        "externalId": "user_12345",
        "displayName": "User 12345 Slack",
        "accessToken": "xoxb-...",
    },
)
data = res.json()

Then resolve the connection by external ID when executing actions:

bash

curl -X POST https://api.weavz.io/api/v1/connections/resolve \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "workspaceId": "proj_abc123",
    "externalId": "user_12345"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { connection } = await client.connections.resolve({
  integrationName: 'slack',
  workspaceId: 'proj_abc123',
  externalId: 'user_12345',
})

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.connections.resolve(
    integration_name="slack",
    workspace_id="proj_abc123",
    external_id="user_12345",
)
connection = result["connection"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/connections/resolve', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    workspaceId: 'proj_abc123',
    externalId: 'user_12345',
  }),
})
const data = await res.json()

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/connections/resolve",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "workspaceId": "proj_abc123",
        "externalId": "user_12345",
    },
)
data = res.json()

Next Steps

End Users — manage per-user connections and connect portals
Integrations — browse available integrations
Connections — learn about connection management
Workspace Integrations API — configure workspace integration instances