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
`limit`	integer	No	Number of connections to return, default `50`, max `100`
`offset`	integer	No	Number of connections to skip for pagination
`includeSuspended`	boolean	No	Include suspended connections. Defaults to `false`

Response (list)

json

{
  "connections": [
    {
      "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
      "externalId": "slack-main",
      "displayName": "Slack (Main Workspace)",
      "integrationName": "slack",
      "authMethodKey": "oauth2",
      "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",
    "authMethodKey": "oauth2",
    "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://platform.weavz.io/api/v1/connections \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

import { WeavzClient } from '@weavz-io/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://platform.weavz.io/api/v1/connections', {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

import httpx
 
res = httpx.get(
    "https://platform.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	Customer-defined `connection.externalId` selector
`displayName`	string	Yes	Human-readable name
`integrationName`	string	Yes	Integration name (e.g., `slack`, `gmail`)
`authMethodKey`	string	Conditional	Auth method key for this credential. Required when an integration exposes multiple compatible auth methods; defaults from `type` for single-auth integrations.
`workspaceId`	string (uuid)	No	Associate with a workspace
`endUserId`	string	No	The end user's `externalId` for per-user connection resolution
`scope`	string	No	`ORGANIZATION`, `WORKSPACE`, or `USER`. Defaults to `ORGANIZATION`. Use `WORKSPACE` for shared workspace credentials and `USER` with `workspaceId` plus `endUserId` for per-user credentials.
`oauthAppId`	string (uuid)	No	Tenant-owned custom OAuth app UUID for OAuth-backed connections. Omit to use the Weavz-managed OAuth app.

When endUserId and workspaceId are provided, endUserId is your user's externalId; Weavz creates or resolves the matching end-user record before storing the connection.

authMethodKey is part of the credential identity. The same integrationName and externalId can have separate credentials for different auth methods, such as api_key and oauth2.

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. Defaults to `{}`

For OAuth connection types, tokenType defaults to Bearer when omitted.

Response (201)

json

{
  "connection": {
    "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "externalId": "openai-prod",
    "displayName": "OpenAI Production",
    "integrationName": "openai",
    "authMethodKey": "api_key",
    "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://platform.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",
    "authMethodKey": "api_key",
    "secretText": "sk-..."
  }'

typescript

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

python

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

typescript

const res = await fetch('https://platform.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',
    authMethodKey: 'api_key',
    secretText: 'sk-...',
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://platform.weavz.io/api/v1/connections",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "type": "SECRET_TEXT",
        "externalId": "openai-prod",
        "displayName": "OpenAI Production",
        "integrationName": "openai",
        "authMethodKey": "api_key",
        "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://platform.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://platform.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://platform.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	`connection.externalId` to resolve
`workspaceId`	string (uuid)	Yes	Workspace scope
`authMethodKey`	string	No	Auth method key to disambiguate multiple credentials for the same integration and external ID
`endUserId`	string	No	The end user's `externalId` 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://platform.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://platform.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://platform.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