End Users

Represent your customers and their connections with a unified identity model.

End Users

End users represent the people who use your product. By registering them in Weavz, you can let each end user connect their own third-party accounts, track their connections, and execute actions on their behalf.

Why End Users?

Without end users, multi-tenant connection management requires manually tracking externalId strings across connections, actions, and connect flows. End users provide a first-class identity that ties everything together:

Each end user owns their connections — when you delete an end user, their connections are cleaned up automatically
Connect portal — generate a URL where an end user can connect their own accounts
Connection resolution — pass endUserId when executing actions and Weavz resolves the right connection
Audit trail — see all connections belonging to a specific end user in one place
MCP servers — create MCP servers scoped to an end user, so AI agents use their connected integrations automatically

End User Types

End users come in two flavors:

Type	Created Via	Identity Field	Use Case
External	API (`POST /api/v1/end-users`)	`externalId`	Your customers — users of your product
Member	Dashboard invitation	`authUserId`	Your team members using the dashboard

Most integrations will use external end users to represent the customers of your SaaS product.

Creating End Users

End users are scoped to a workspace. Each externalId must be unique within its workspace.

bash

curl -X POST https://api.weavz.io/api/v1/end-users \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "user_123",
    "displayName": "Alice Johnson",
    "email": "[email protected]",
    "metadata": {
      "plan": "pro",
      "company": "Acme Inc"
    }
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { endUser } = await client.endUsers.create({
  workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  externalId: 'user_123',
  displayName: 'Alice Johnson',
  email: '[email protected]',
  metadata: {
    plan: 'pro',
    company: 'Acme Inc',
  },
})

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.end_users.create(
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    external_id="user_123",
    display_name="Alice Johnson",
    email="[email protected]",
    metadata={"plan": "pro", "company": "Acme Inc"},
)
end_user = result["endUser"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/end-users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    externalId: 'user_123',
    displayName: 'Alice Johnson',
    email: '[email protected]',
    metadata: { plan: 'pro', company: 'Acme Inc' },
  }),
})
const { endUser } = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/end-users",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "externalId": "user_123",
        "displayName": "Alice Johnson",
        "email": "[email protected]",
        "metadata": {"plan": "pro", "company": "Acme Inc"},
    },
)
end_user = res.json()["endUser"]

Auto-Creation

End users can also be created automatically when a connection is established through the hosted connect flow with an endUserId parameter. If the end user doesn't exist yet, Weavz creates one for you.

Connect Portal

The connect portal lets your end users connect their own third-party accounts through a hosted page. Generate a portal URL for an end user:

bash

curl -X POST https://api.weavz.io/api/v1/end-users/{endUserId}/connect-token \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { connectUrl, token, expiresAt } = await client.endUsers.createConnectToken(
  endUser.id,
  { integrationName: 'slack' }
)
 
// Open connectUrl in a popup or redirect the end user to it

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.end_users.create_connect_token(
    end_user["id"],
    integration_name="slack",
)
connect_url = result["connectUrl"]
 
# Open connect_url in a popup or redirect the end user to it

typescript

const res = await fetch(`https://api.weavz.io/api/v1/end-users/${endUserId}/connect-token`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ integrationName: 'slack' }),
})
const { connectUrl, token, expiresAt } = await res.json()

python

import httpx
 
res = httpx.post(
    f"https://api.weavz.io/api/v1/end-users/{end_user_id}/connect-token",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={"integrationName": "slack"},
)
data = res.json()
connect_url = data["connectUrl"]

Portal modes

Single integration — pass integrationName to restrict the portal to one integration (e.g., only Slack)
Multi-integration — omit integrationName to let the user connect any integration configured in the workspace

Connection Ownership

Every connection created through the connect portal is automatically linked to the end user. You can view all connections for an end user:

bash

curl https://api.weavz.io/api/v1/end-users/{endUserId} \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

const { endUser, connections } = await client.endUsers.get(endUserId)
console.log(`${endUser.displayName} has ${connections.length} connections`)

python

result = client.end_users.get(end_user_id)
end_user = result["endUser"]
connections = result["connections"]
print(f"{end_user['displayName']} has {len(connections)} connections")

typescript

const res = await fetch(`https://api.weavz.io/api/v1/end-users/${endUserId}`, {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const { endUser, connections } = await res.json()

python

import httpx
 
res = httpx.get(
    f"https://api.weavz.io/api/v1/end-users/{end_user_id}",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()
connections = data["connections"]

When you delete an end user, all their connections are deleted as well.

Connection Strategies

End users work with workspace integration connection strategies:

Strategy	End User Behavior
`fixed`	All end users share the same connection. No per-user connections.
`per_user`	Each end user must connect their own account. No fallback.
`per_user_with_fallback`	End users can connect their own account, with a shared default fallback.

When you execute an action with endUserId, Weavz looks up the end user's connection for that integration. With per_user_with_fallback, if the end user hasn't connected their own account, the workspace's default connection is used instead.

Executing Actions as an End User

Pass endUserId when executing actions to use the end user's connection:

bash

curl -X POST https://api.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "actionName": "send_channel_message",
    "input": {
      "channel": "C0123456789",
      "text": "Hello from the user!"
    },
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "endUserId": "user_123"
  }'

typescript

const result = await client.actions.execute('slack', 'send_channel_message', {
  workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  endUserId: 'user_123',
  input: {
    channel: 'C0123456789',
    text: 'Hello from the user!',
  },
})

python

result = client.actions.execute(
    "slack",
    "send_channel_message",
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    end_user_id="user_123",
    input={
        "channel": "C0123456789",
        "text": "Hello from the user!",
    },
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    actionName: 'send_channel_message',
    input: { channel: 'C0123456789', text: 'Hello from the user!' },
    workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    endUserId: 'user_123',
  }),
})
const data = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "actionName": "send_channel_message",
        "input": {"channel": "C0123456789", "text": "Hello from the user!"},
        "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "endUserId": "user_123",
    },
)
data = res.json()

Email Invitations

If an end user has an email address, you can send them an invitation with a link to connect their accounts:

bash

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

typescript

await client.endUsers.invite(endUser.id, {
  email: '[email protected]',
  integrationName: 'slack',
})

python

client.end_users.invite(
    end_user["id"],
    email="[email protected]",
    integration_name="slack",
)

typescript

await fetch(`https://api.weavz.io/api/v1/end-users/${endUserId}/invite`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    integrationName: 'slack',
  }),
})

python

import httpx
 
httpx.post(
    f"https://api.weavz.io/api/v1/end-users/{end_user_id}/invite",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "email": "[email protected]",
        "integrationName": "slack",
    },
)

The email contains a link to the connect portal where the end user can authenticate with the specified integration.

Next Steps

End Users API Reference — full endpoint documentation
Managing End Users — step-by-step guide
Connections — learn about connection ownership and resolution
Organizations & Workspaces — understand the resource hierarchy