Connect

Create connections via the hosted connect flow for OAuth2 and all other authentication types.

Connect

The Connect endpoints provide a hosted connect flow for creating connections across all authentication types (OAuth2, API keys, custom auth). Weavz hosts the entire authorization process — you create a session token, open the connect page, and retrieve the result.

Hosted Connect Flow

POST/api/v1/connect/token

Create a connect session token. Returns a token and a connectUrl that you open in a popup or redirect to start the authorization flow.

Request Body

Field	Type	Required	Description
`integrationName`	string	Yes	Integration to connect (e.g., `slack`, `google-sheets`)
`connectionName`	string	Yes	Display name for the resulting connection
`externalId`	string	Yes	External identifier for the connection (for multi-tenant scoping)
`workspaceId`	string (uuid)	Yes	Workspace to create the connection in
`endUserId`	string	No	End user external ID to associate the connection with
`scope`	string	No	Connection scope: `ORGANIZATION`, `WORKSPACE`, or `USER`

Response

json

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

Example

bash

curl -X POST https://api.weavz.io/api/v1/connect/token \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "google-sheets",
    "connectionName": "Google Sheets",
    "externalId": "tenant_123_gsheets",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { token, connectUrl } = await client.connect.createToken({
  integrationName: 'google-sheets',
  connectionName: 'Google Sheets',
  externalId: 'tenant_123_gsheets',
  workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
})

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.connect.create_token(
    integration_name="google-sheets",
    connection_name="Google Sheets",
    external_id="tenant_123_gsheets",
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/connect/token', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'google-sheets',
    connectionName: 'Google Sheets',
    externalId: 'tenant_123_gsheets',
    workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  }),
})
const data = await res.json()

python

import httpx
 
res = httpx.post(
    "https://api.weavz.io/api/v1/connect/token",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "google-sheets",
        "connectionName": "Google Sheets",
        "externalId": "tenant_123_gsheets",
        "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
data = res.json()

Open the connectUrl in a popup window or redirect the user to it. The hosted page handles the full OAuth2 consent flow.

Errors

Status	Code	Description
`400`	`NOT_OAUTH2`	Integration does not support OAuth2
`400`	`MISSING_OAUTH2_CONFIG`	No OAuth app configured for this integration
`404`	`INTEGRATION_NOT_FOUND`	Integration not found

GET/api/v1/connect/session/:sessionId

Retrieve the status and result of a connect session. Poll this endpoint after the user completes (or closes) the connect page.

Path Parameters

Field	Type	Description
`sessionId`	string	The token returned from `POST /api/v1/connect/token`

Response

json

{
  "status": "completed",
  "connection": {
    "id": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "externalId": "tenant_123_gsheets",
    "displayName": "Google Sheets",
    "integrationName": "google-sheets",
    "type": "PLATFORM_OAUTH2",
    "status": "ACTIVE",
    "scope": "ORGANIZATION",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}

Session statuses:

Status	Description
`pending`	Connect page not yet opened or user still authorizing
`completed`	Authorization succeeded, `connection` field contains the new connection
`failed`	Authorization failed, `error` field contains the error message

Example

bash

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

typescript

const { session } = await client.connect.getSession('cs_abc123def456')

python

result = client.connect.get_session("cs_abc123def456")

typescript

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

python

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

Errors

Status	Code	Description
`404`	`SESSION_NOT_FOUND`	Connect session not found or expired