Connections

Manage integration connections and credentials.

Connections

Connections store authentication credentials for third-party integrations. Each connection is tied to a specific integration (e.g., Slack, Gmail) and can be scoped to an organization, workspace, or individual user.

List Connections

GET/api/v1/connections

List all connections in your organization, or fetch a single connection by ID.

Query Parameters

Field	Type	Required	Description
`id`	string (uuid)	No	Fetch a specific connection by ID

Response (list)

json

{
  "connections": [
    {
      "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "externalId": "slack-main",
      "displayName": "Slack (Main Workspace)",
      "integrationName": "slack",
      "type": "PLATFORM_OAUTH2",
      "status": "ACTIVE",
      "scope": "ORGANIZATION",
      "workspaceId": null,
      "endUserId": null,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 1
}

Response (single, with ?id=...)

json

{
  "connection": {
    "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "externalId": "slack-main",
    "displayName": "Slack (Main Workspace)",
    "integrationName": "slack",
    "type": "PLATFORM_OAUTH2",
    "status": "ACTIVE",
    "scope": "ORGANIZATION",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Example

bash

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

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { connections } = await client.connections.list()

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.connections.list()
connections = result["connections"]

typescript

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

python

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

Create Connection

POST/api/v1/connections

Create a new connection with stored credentials.

Request Body

Field	Type	Required	Description
`type`	string	Yes	One of: `SECRET_TEXT`, `BASIC_AUTH`, `CUSTOM_AUTH`, `OAUTH2`, `PLATFORM_OAUTH2`
`externalId`	string	Yes	Unique external identifier for this connection
`displayName`	string	Yes	Human-readable name
`integrationName`	string	Yes	Integration name (e.g., `slack`, `gmail`)
`workspaceId`	string (uuid)	No	Associate with a workspace
`endUserId`	string	No	Your end-user's identifier for per-user connection resolution
`scope`	string	No	`ORGANIZATION`, `WORKSPACE`, or `USER`

Type-Specific Fields

For SECRET_TEXT:

Field	Type	Required	Description
`secretText`	string	Yes	The secret value (API key, token, etc.)

For BASIC_AUTH:

Field	Type	Required	Description
`username`	string	Yes	Username
`password`	string	Yes	Password

For CUSTOM_AUTH:

Field	Type	Required	Description
`props`	object	Yes	Custom authentication properties

For OAUTH2 / PLATFORM_OAUTH2:

Field	Type	Required	Description
`accessToken`	string	Yes	OAuth access token
`refreshToken`	string	No	OAuth refresh token
`tokenType`	string	No	Token type (e.g., `Bearer`)
`expiresIn`	integer	No	Token expiry in seconds
`scope_oauth`	string	No	OAuth scopes granted
`data`	object	No	Additional OAuth data

Response (201)

json

{
  "connection": {
    "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "externalId": "openai-prod",
    "displayName": "OpenAI Production",
    "integrationName": "openai",
    "type": "SECRET_TEXT",
    "status": "ACTIVE",
    "scope": "ORGANIZATION",
    "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/connections \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SECRET_TEXT",
    "externalId": "openai-prod",
    "displayName": "OpenAI Production",
    "integrationName": "openai",
    "secretText": "sk-..."
  }'

typescript

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

python

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

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: 'SECRET_TEXT',
    externalId: 'openai-prod',
    displayName: 'OpenAI Production',
    integrationName: 'openai',
    secretText: 'sk-...',
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/connections",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "type": "SECRET_TEXT",
        "externalId": "openai-prod",
        "displayName": "OpenAI Production",
        "integrationName": "openai",
        "secretText": "sk-...",
    },
)
data = res.json()

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing or invalid fields
`403`	`QUOTA_EXCEEDED`	Connection limit reached
`409`	`DUPLICATE`	Connection with this `externalId` already exists

Delete Connection

DELETE/api/v1/connections/:id

Delete a connection.

Path Parameters

Field	Type	Description
`id`	string (uuid)	Connection ID

Response

json

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

Example

bash

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

typescript

await client.connections.delete('c1d2e3f4-5678-90ab-cdef-1234567890ab')

python

client.connections.delete("c1d2e3f4-5678-90ab-cdef-1234567890ab")

typescript

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

python

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

Errors

Status	Code	Description
`404`	`NOT_FOUND`	Connection not found

Resolve Connection

POST/api/v1/connections/resolve

Find a connection by integration name and optional scoping parameters. This is useful when you know the integration and external ID but not the connection's internal UUID.

Request Body

Field	Type	Required	Description
`integrationName`	string	Yes	Integration name
`externalId`	string	No	External identifier
`workspaceId`	string (uuid)	Yes	Workspace scope
`endUserId`	string	No	Your end-user's identifier for per-user connection resolution

Response

json

{
  "connection": {
    "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "externalId": "slack-main",
    "displayName": "Slack (Main Workspace)",
    "integrationName": "slack",
    "type": "PLATFORM_OAUTH2",
    "status": "ACTIVE",
    "scope": "ORGANIZATION",
    "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/connections/resolve \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "slack",
    "externalId": "slack-main",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

typescript

const { connection } = await client.connections.resolve({
  integrationName: 'slack',
  workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  externalId: 'slack-main',
})

python

result = client.connections.resolve(
    integration_name="slack",
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    external_id="slack-main",
)

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',
    externalId: 'slack-main',
    workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/connections/resolve",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "slack",
        "externalId": "slack-main",
        "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
data = res.json()

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing integration name
`404`	`CONNECTION_NOT_FOUND`	No matching connection found