Setting Up Connections

Connect third-party services to Weavz using OAuth2, API keys, or custom authentication.

Connections store the authentication credentials needed to interact with third-party services. Weavz supports OAuth2, API key, and custom authentication methods.

Connection Types

Type	Use Case	Example
`OAUTH2`	OAuth2 authorization flow	Google, Slack, GitHub
`PLATFORM_OAUTH2`	Platform-managed OAuth2 (pre-configured)	Slack, Notion, Airtable
`SECRET_TEXT`	Single API key or token	OpenAI, Anthropic, SendGrid
`BASIC_AUTH`	Username and password	SMTP, legacy APIs
`CUSTOM_AUTH`	Multi-field authentication	Custom services

OAuth2 connections use the hosted connect flow — a Weavz-hosted page that handles the full authorization process. You create a connect token, open the connect page (as a popup or redirect), and the user completes authorization there. Once finished, you retrieve the session to get the resulting connection.

OAuth App Selection

OAuth2 integrations can use two OAuth app sources:

Source	Availability	Selection
Platform-managed OAuth app	Default where Weavz has configured provider credentials	Omit `oauthAppId`; Weavz uses the platform app unless your organization has a permitted tenant-owned app for the integration
Tenant-owned custom OAuth app	Team, Scale, and Enterprise	Register it in Settings > OAuth Apps; new connections for that integration use it automatically, or pass `oauthAppId` to select a specific app

The connection type does not decide whether the provider sees a Weavz-managed OAuth client or your own OAuth client. That choice comes from OAuth app selection during hosted connect. If neither a platform-managed app nor an eligible tenant-owned app exists for the integration, creating the connect token returns NO_OAUTH_APP.

Navigate to Connections

Open the Connections page from the sidebar.

Create Connection

Click Create Connection and select the integration (e.g., Slack) from the picker.

Authorize

Click Authorize — a popup opens with the provider's consent screen.

Approve Access

Approve access in the popup — it closes automatically and your connection appears in the list.

The hosted connect flow has three steps: create a token, open the connect page, and retrieve the session result.

Step 1: Create a Connect Token

bash

curl -X POST https://api.weavz.io/api/v1/connect/token \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "connectionName": "My Slack Workspace",
    "externalId": "tenant_123_slack",
    "workspaceId": "YOUR_WORKSPACE_ID"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_key' })
 
const { token, connectUrl } = await client.connect.createToken({
  integrationName: 'slack',
  connectionName: 'My Slack Workspace',
  externalId: 'tenant_123_slack',
  workspaceId: 'YOUR_WORKSPACE_ID',
})

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_key")
 
result = client.connect.create_token(
    integration_name="slack",
    connection_name="My Slack Workspace",
    external_id="tenant_123_slack",
    workspace_id="YOUR_WORKSPACE_ID",
)
 
token = result["token"]
connect_url = result["connectUrl"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/connect/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'slack',
    connectionName: 'My Slack Workspace',
    externalId: 'tenant_123_slack',
    workspaceId: 'YOUR_WORKSPACE_ID',
  }),
})
 
const { token, connectUrl } = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/connect/token",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "integrationName": "slack",
        "connectionName": "My Slack Workspace",
        "externalId": "tenant_123_slack",
        "workspaceId": "YOUR_WORKSPACE_ID",
    },
)
 
data = res.json()
token = data["token"]
connect_url = data["connectUrl"]

Response:

json

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

This example creates a workspace-scoped connection with the default OAuth app selection. Connect token creation also accepts:

Option	Use when
`endUserId`	The connection should belong to a specific end user, identified by their `externalId`
`scope`	You need to explicitly choose `ORGANIZATION`, `WORKSPACE`, or `USER` connection scope
`oauthAppId`	You want to force a specific tenant-owned OAuth app instead of default app selection
`successRedirectUri`	Your product should receive the user after successful authorization
`errorRedirectUri`	Your product should receive the user after a failed authorization

See the Connect API reference for the complete request body and OAuth app selection errors.

Step 2: Open the Connect Page

Open connectUrl in a popup window or redirect the user to it. The hosted connect page guides them through the OAuth2 consent flow.

In a browser environment, the TypeScript SDK provides a convenience method that handles the popup automatically:

typescript

// First create a token, then open popup
const { token, connectUrl } = await client.connect.createToken({
  integrationName: 'slack',
  connectionName: 'My Slack Workspace',
  externalId: 'tenant_123_slack',
  workspaceId: 'YOUR_WORKSPACE_ID',
})
 
// Opens a popup, waits for completion, returns the connection result
const result = await client.connect.popup({ token, connectUrl })
 
console.log('Connection created:', result.connectionId)

Step 3: Retrieve the Session

If you opened the connect page manually (not using the popup helper), poll the session endpoint to check when the user has completed authorization:

bash

curl -X POST https://api.weavz.io/api/v1/connect/session/poll \
  -H "Content-Type: application/json" \
  -d '{"token":"cst_your_connect_token"}'

typescript

const session = await client.connect.wait(token)
 
if (session.status === 'COMPLETED') {
  console.log('Connection created:', session.connectionId)
} else if (session.status === 'FAILED') {
  console.error('Connect failed:', session.error)
}

python

session = client.connect.wait(token)
 
if session["status"] == "COMPLETED":
    print("Connection created:", session["connectionId"])
elif session["status"] == "FAILED":
    print("Connect failed:", session["error"])

typescript

const res = await fetch('https://api.weavz.io/api/v1/connect/session/poll', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token }),
})
 
const session = await res.json()
 
if (session.status === 'COMPLETED') {
  console.log('Connection created:', session.connectionId)
} else if (session.status === 'FAILED') {
  console.error('Connect failed:', session.error)
}

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/connect/session/poll",
    json={"token": token},
)
 
session = res.json()
 
if session["status"] == "COMPLETED":
    print("Connection created:", session["connectionId"])
elif session["status"] == "FAILED":
    print("Connect failed:", session["error"])

API Key Connections

For services that use API keys or tokens:

Navigate to Connections

Open the Connections page from the sidebar.

Create Connection

Click Create Connection and select the integration (e.g., OpenAI).

Enter Credentials

Enter your API key in the form.

Save

Optionally set a display name and external ID, then click Save.

bash

curl -X POST https://api.weavz.io/api/v1/connections \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SECRET_TEXT",
    "integrationName": "openai",
    "externalId": "tenant_123_openai",
    "displayName": "OpenAI Production",
    "secretText": "sk-proj-abc123..."
  }'

typescript

const { connection } = await client.connections.create({
  type: 'SECRET_TEXT',
  integrationName: 'openai',
  externalId: 'tenant_123_openai',
  displayName: 'OpenAI Production',
  secretText: 'sk-proj-abc123...',
})

python

result = client.connections.create(
    type="SECRET_TEXT",
    integration_name="openai",
    external_id="tenant_123_openai",
    display_name="OpenAI Production",
    secret_text="sk-proj-abc123...",
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/connections', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'SECRET_TEXT',
    integrationName: 'openai',
    externalId: 'tenant_123_openai',
    displayName: 'OpenAI Production',
    secretText: 'sk-proj-abc123...',
  }),
})
 
const { connection } = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/connections",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "type": "SECRET_TEXT",
        "integrationName": "openai",
        "externalId": "tenant_123_openai",
        "displayName": "OpenAI Production",
        "secretText": "sk-proj-abc123...",
    },
)
 
connection = res.json()["connection"]

Direct connection creation also accepts workspaceId, endUserId, scope, and auth-type-specific fields. scope defaults to ORGANIZATION; pass workspaceId plus endUserId when creating a user-scoped connection for an end user's externalId. See the Connections API reference.

Custom Auth Connections

For integrations requiring multiple fields:

Navigate to Connections

Open the Connections page from the sidebar.

Create Connection

Click Create Connection and select the integration (e.g., Freshsales).

Fill in Fields

The form dynamically renders the required fields for the integration. Fill in all required values (e.g., base URL and API key).

Save

Set a display name and external ID, then click Save.

bash

curl -X POST https://api.weavz.io/api/v1/connections \
  -H "Authorization: Bearer wvz_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CUSTOM_AUTH",
    "integrationName": "freshsales",
    "externalId": "tenant_123_freshsales",
    "displayName": "Freshsales CRM",
    "props": {
      "base_url": "https://mycompany.freshsales.io",
      "api_key": "abc123..."
    }
  }'

typescript

const { connection } = await client.connections.create({
  type: 'CUSTOM_AUTH',
  integrationName: 'freshsales',
  externalId: 'tenant_123_freshsales',
  displayName: 'Freshsales CRM',
  props: {
    base_url: 'https://mycompany.freshsales.io',
    api_key: 'abc123...',
  },
})

python

result = client.connections.create(
    type="CUSTOM_AUTH",
    integration_name="freshsales",
    external_id="tenant_123_freshsales",
    display_name="Freshsales CRM",
    props={
        "base_url": "https://mycompany.freshsales.io",
        "api_key": "abc123...",
    },
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/connections', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'CUSTOM_AUTH',
    integrationName: 'freshsales',
    externalId: 'tenant_123_freshsales',
    displayName: 'Freshsales CRM',
    props: {
      base_url: 'https://mycompany.freshsales.io',
      api_key: 'abc123...',
    },
  }),
})
 
const { connection } = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/connections",
    headers={"Authorization": "Bearer wvz_your_key"},
    json={
        "type": "CUSTOM_AUTH",
        "integrationName": "freshsales",
        "externalId": "tenant_123_freshsales",
        "displayName": "Freshsales CRM",
        "props": {
            "base_url": "https://mycompany.freshsales.io",
            "api_key": "abc123...",
        },
    },
)
 
connection = res.json()["connection"]

End User Connections

For multi-tenant applications, use end users to manage per-user connections. Register an end user, then generate a connect URL for them:

typescript

// Register the end user
const { endUser } = await client.endUsers.create({
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  externalId: 'user_456',
  displayName: 'Alice Johnson',
})
 
// Generate a connect URL for Slack
const { connectUrl } = await client.endUsers.createConnectToken(
  endUser.id,
  { integrationName: 'slack' }
)
 
// Open connectUrl in a popup for the user to authorize

python

# Register the end user
result = client.end_users.create(
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    external_id="user_456",
    display_name="Alice Johnson",
)
end_user = result["endUser"]
 
# Generate a connect URL for Slack
result = client.end_users.create_connect_token(
    end_user["id"],
    integration_name="slack",
)
connect_url = result["connectUrl"]
 
# Open connect_url in a popup for the user to authorize

typescript

// Register the end user
const userRes = await fetch('https://api.weavz.io/api/v1/end-users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    externalId: 'user_456',
    displayName: 'Alice Johnson',
  }),
})
const { endUser } = await userRes.json()
 
// Generate a connect URL for Slack
const tokenRes = await fetch(
  `https://api.weavz.io/api/v1/end-users/${endUser.id}/connect-token`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer wvz_your_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ integrationName: 'slack' }),
  }
)
const { connectUrl } = await tokenRes.json()

python

import httpx
 
headers = {"Authorization": "Bearer wvz_your_key"}
 
# Register the end user
res = httpx.post(
    "https://api.weavz.io/api/v1/end-users",
    headers=headers,
    json={
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "externalId": "user_456",
        "displayName": "Alice Johnson",
    },
)
end_user = res.json()["endUser"]
 
# Generate a connect URL for Slack
res = httpx.post(
    f"https://api.weavz.io/api/v1/end-users/{end_user['id']}/connect-token",
    headers=headers,
    json={"integrationName": "slack"},
)
connect_url = res.json()["connectUrl"]

Connections created through the end user connect portal are automatically linked to the end user. When executing actions, pass endUserId to resolve the end user's connection:

typescript

const result = await client.actions.execute('slack', 'send_channel_message', {
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  endUserId: 'user_456',
  input: { channel: 'C0123456789', text: 'Hello!' },
})

python

result = client.actions.execute(
    "slack",
    "send_channel_message",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    end_user_id="user_456",
    input={"channel": "C0123456789", "text": "Hello!"},
)

See Managing End Users for the full workflow.

Connection External IDs

Connection external IDs are your stable identifiers for individual credential sets. Use them when your backend needs to retrieve or execute against a specific connection, such as a project API key, shared customer bot, or tenant-level account.

For per-user credentials, use end users instead: store your user's ID in endUser.externalId and pass that value as endUserId during execution.

When resolving by connection external ID, always pass the same context you used when creating or using the connection. workspaceId is required for resolution, and mismatched scope is rejected.

typescript

// Create a connection with an external ID
await client.connections.create({
  type: 'SECRET_TEXT',
  integrationName: 'openai',
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  externalId: 'conn_project_alpha_openai',
  displayName: 'Project Alpha OpenAI Key',
  secretText: 'sk-...',
})
 
// Later, resolve the connection by external ID
const { connection } = await client.connections.resolve({
  integrationName: 'openai',
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  externalId: 'conn_project_alpha_openai',
})

python

# Create a connection with an external ID
client.connections.create(
    type="SECRET_TEXT",
    integration_name="openai",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    external_id="conn_project_alpha_openai",
    display_name="Project Alpha OpenAI Key",
    secret_text="sk-...",
)
 
# Later, resolve the connection by external ID
result = client.connections.resolve(
    integration_name="openai",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    external_id="conn_project_alpha_openai",
)

typescript

// Create a connection with an external ID
await fetch('https://api.weavz.io/api/v1/connections', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'SECRET_TEXT',
    integrationName: 'openai',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    externalId: 'conn_project_alpha_openai',
    displayName: 'Project Alpha OpenAI Key',
    secretText: 'sk-...',
  }),
})
 
// Later, resolve the connection by external ID
const res = await fetch('https://api.weavz.io/api/v1/connections/resolve', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'openai',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    externalId: 'conn_project_alpha_openai',
  }),
})
 
const { connection } = await res.json()

python

import httpx
 
headers = {"Authorization": "Bearer wvz_your_key"}
 
# Create a connection with an external ID
httpx.post(
    "https://api.weavz.io/api/v1/connections",
    headers=headers,
    json={
        "type": "SECRET_TEXT",
        "integrationName": "openai",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "externalId": "conn_project_alpha_openai",
        "displayName": "Project Alpha OpenAI Key",
        "secretText": "sk-...",
    },
)
 
# Later, resolve the connection by external ID
res = httpx.post(
    "https://api.weavz.io/api/v1/connections/resolve",
    headers=headers,
    json={
        "integrationName": "openai",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "externalId": "conn_project_alpha_openai",
    },
)
 
connection = res.json()["connection"]

Token Refresh

OAuth2 tokens are automatically refreshed when needed — no manual intervention required.

Listing Connections

bash

curl https://api.weavz.io/api/v1/connections \
  -H "Authorization: Bearer wvz_your_key"

typescript

const { connections } = await client.connections.list()

python

result = client.connections.list()
connections = result["connections"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/connections', {
  headers: { 'Authorization': 'Bearer wvz_your_key' },
})
 
const { connections } = await res.json()

python

import httpx
 
res = httpx.get(
    "https://api.weavz.io/api/v1/connections",
    headers={"Authorization": "Bearer wvz_your_key"},
)
 
connections = res.json()["connections"]

Deleting Connections

bash

curl -X DELETE https://api.weavz.io/api/v1/connections/CONNECTION_UUID \
  -H "Authorization: Bearer wvz_your_key"

typescript

await client.connections.delete('CONNECTION_UUID')

python

client.connections.delete("CONNECTION_UUID")

typescript

await fetch('https://api.weavz.io/api/v1/connections/CONNECTION_UUID', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer wvz_your_key' },
})

python

import httpx
 
httpx.delete(
    "https://api.weavz.io/api/v1/connections/CONNECTION_UUID",
    headers={"Authorization": "Bearer wvz_your_key"},
)