End Users

Manage end user identities and their integration connections.

End Users

End users represent the people who use your product. Each end user is scoped to a workspace and can own connections to third-party integrations.

Create End User

POST/api/v1/end-users

Create a new end user within a workspace.

Request Body

Field	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Workspace to create the end user in
`externalId`	string	Yes	Unique external identifier within the workspace
`displayName`	string	No	Human-readable display name
`email`	string (email)	No	End user email address
`metadata`	object	No	Arbitrary metadata to attach

Response (201)

json

{
  "endUser": {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "user_123",
    "displayName": "Alice Johnson",
    "email": "[email protected]",
    "metadata": { "plan": "pro" },
    "type": "external",
    "connectionCount": 0,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Example

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" }
  }'

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' },
})

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"},
)
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' },
  }),
})
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"},
    },
)
end_user = res.json()["endUser"]

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing or invalid fields
`409`	`DUPLICATE`	End user with this `externalId` already exists in the workspace

List End Users

GET/api/v1/end-users

List all end users in a workspace.

Query Parameters

Field	Type	Required	Description
`workspaceId`	string (uuid)	Yes	Filter by workspace ID

Response

json

{
  "endUsers": [
    {
      "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "externalId": "user_123",
      "displayName": "Alice Johnson",
      "email": "[email protected]",
      "metadata": { "plan": "pro" },
      "type": "external",
      "connectionCount": 2,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 1
}

Example

bash

curl "https://api.weavz.io/api/v1/end-users?workspaceId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { endUsers, total } = await client.endUsers.list({
  workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
})

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.end_users.list(
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
)
end_users = result["endUsers"]

typescript

const res = await fetch(
  'https://api.weavz.io/api/v1/end-users?workspaceId=a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  { headers: { 'Authorization': 'Bearer wvz_your_api_key' } }
)
const { endUsers, total } = await res.json()

python

import httpx
 
res = httpx.get(
    "https://api.weavz.io/api/v1/end-users",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    params={"workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"},
)
data = res.json()
end_users = data["endUsers"]

Get End User

GET/api/v1/end-users/:id

Get an end user by ID, including their connections.

Path Parameters

Field	Type	Description
`id`	string (uuid)	End user ID

Response

json

{
  "endUser": {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "user_123",
    "displayName": "Alice Johnson",
    "email": "[email protected]",
    "metadata": { "plan": "pro" },
    "type": "external",
    "connectionCount": 2,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  },
  "connections": [
    {
      "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "externalId": "user_123_slack",
      "displayName": "Alice's Slack",
      "integrationName": "slack",
      "type": "PLATFORM_OAUTH2",
      "status": "ACTIVE",
      "createdAt": "2025-01-15T12:00:00.000Z",
      "updatedAt": "2025-01-15T12:00:00.000Z"
    }
  ]
}

Example

bash

curl https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { endUser, connections } = await client.endUsers.get(
  'a1b2c3d4-5678-90ab-cdef-1234567890ab'
)

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.end_users.get("a1b2c3d4-5678-90ab-cdef-1234567890ab")
end_user = result["endUser"]
connections = result["connections"]

typescript

const res = await fetch(
  'https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab',
  { headers: { 'Authorization': 'Bearer wvz_your_api_key' } }
)
const { endUser, connections } = await res.json()

python

import httpx
 
res = httpx.get(
    "https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()
end_user = data["endUser"]
connections = data["connections"]

Errors

Status	Code	Description
`404`	`NOT_FOUND`	End user not found

Update End User

PATCH/api/v1/end-users/:id

Update an end user's display name, email, or metadata.

Path Parameters

Field	Type	Description
`id`	string (uuid)	End user ID

Request Body

Field	Type	Required	Description
`displayName`	string \| null	No	Updated display name (null to clear)
`email`	string \| null	No	Updated email address (null to clear)
`metadata`	object \| null	No	Updated metadata (null to clear)

Response

json

{
  "endUser": {
    "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "externalId": "user_123",
    "displayName": "Alice J.",
    "email": "[email protected]",
    "metadata": { "plan": "enterprise" },
    "type": "external",
    "connectionCount": 2,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-16T08:00:00.000Z"
  }
}

Example

bash

curl -X PATCH https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Alice J.",
    "metadata": { "plan": "enterprise" }
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { endUser } = await client.endUsers.update(
  'a1b2c3d4-5678-90ab-cdef-1234567890ab',
  {
    displayName: 'Alice J.',
    metadata: { plan: 'enterprise' },
  }
)

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.end_users.update(
    "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    display_name="Alice J.",
    metadata={"plan": "enterprise"},
)
end_user = result["endUser"]

typescript

const res = await fetch(
  'https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer wvz_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      displayName: 'Alice J.',
      metadata: { plan: 'enterprise' },
    }),
  }
)
const { endUser } = await res.json()

python

import httpx
 
res = httpx.patch(
    "https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "displayName": "Alice J.",
        "metadata": {"plan": "enterprise"},
    },
)
end_user = res.json()["endUser"]

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	No updates provided
`404`	`NOT_FOUND`	End user not found

Delete End User

DELETE/api/v1/end-users/:id

Delete an end user and cascade-delete all their connections.

Path Parameters

Field	Type	Description
`id`	string (uuid)	End user ID

Response

json

{
  "deleted": true,
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

Example

bash

curl -X DELETE https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
await client.endUsers.delete('a1b2c3d4-5678-90ab-cdef-1234567890ab')

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
client.end_users.delete("a1b2c3d4-5678-90ab-cdef-1234567890ab")

typescript

const res = await fetch(
  'https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab',
  {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer wvz_your_api_key' },
  }
)
const data = await res.json()

python

import httpx
 
res = httpx.delete(
    "https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Errors

Status	Code	Description
`404`	`NOT_FOUND`	End user not found

Generate Connect Token

POST/api/v1/end-users/:id/connect-token

Generate a connect portal URL for an end user. The portal lets them connect their own third-party accounts.

Path Parameters

Field	Type	Description
`id`	string (uuid)	End user ID

Request Body

Field	Type	Required	Description
`integrationName`	string	No	Restrict to a specific integration
`expiresIn`	integer	No	Token expiration in seconds (default: 14400 = 4 hours)

Response

json

{
  "connectUrl": "https://api.weavz.io/connect?token=cst_abc123...",
  "token": "cst_abc123...",
  "expiresAt": "2025-01-15T14:30:00.000Z"
}

Example

bash

curl -X POST https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab/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(
  'a1b2c3d4-5678-90ab-cdef-1234567890ab',
  { integrationName: 'slack' }
)

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.end_users.create_connect_token(
    "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    integration_name="slack",
)
connect_url = result["connectUrl"]

typescript

const res = await fetch(
  'https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab/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(
    "https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab/connect-token",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={"integrationName": "slack"},
)
data = res.json()
connect_url = data["connectUrl"]

Errors

Status	Code	Description
`404`	`NOT_FOUND`	End user not found

Send Email Invitation

POST/api/v1/end-users/:id/invite

Send an email invitation to an end user with a link to connect their accounts.

Path Parameters

Field	Type	Description
`id`	string (uuid)	End user ID

Request Body

Field	Type	Required	Description
`email`	string (email)	Yes	Email address to send the invitation to
`integrationName`	string	No	Restrict to a specific integration
`expiresIn`	integer	No	Link expiration in seconds (default: 14400 = 4 hours)

Response

json

{
  "sent": true,
  "email": "[email protected]"
}

Example

bash

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

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { sent } = await client.endUsers.invite(
  'a1b2c3d4-5678-90ab-cdef-1234567890ab',
  {
    email: '[email protected]',
    integrationName: 'slack',
  }
)

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.end_users.invite(
    "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    email="[email protected]",
    integration_name="slack",
)

typescript

const res = await fetch(
  'https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab/invite',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer wvz_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: '[email protected]',
      integrationName: 'slack',
    }),
  }
)
const data = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/end-users/a1b2c3d4-5678-90ab-cdef-1234567890ab/invite",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "email": "[email protected]",
        "integrationName": "slack",
    },
)
data = res.json()

Errors

Status	Code	Description
`400`	`EMAIL_NOT_CONFIGURED`	Email sending is not configured
`404`	`NOT_FOUND`	End user not found