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	Customer-defined connection `externalId` selector
`workspaceId`	string (uuid)	Yes	Workspace to create the connection in
`endUserId`	string	No	The end user's `externalId` to associate the connection with
`scope`	string	No	Connection scope: `ORGANIZATION`, `WORKSPACE`, or `USER`. Defaults to `ORGANIZATION`
`oauthAppId`	string (uuid)	No	Specific OAuth app to use for OAuth2 integrations. Usually omit this so Weavz selects an eligible tenant-owned app first, then a platform-managed app when available.
`successRedirectUri`	string (url)	No	URL to redirect to after a successful hosted connect flow
`errorRedirectUri`	string (url)	No	URL to redirect to after a failed hosted connect flow

Response

json

{
  "token": "cst_550e8400-e29b-41d4-a716-446655440000",
  "connectUrl": "https://api.weavz.io/connect?token=cst_550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2025-01-15T14:30:00.000Z"
}

Connect session tokens expire after 4 hours. Use the returned expiresAt to decide when your frontend should stop polling or ask your backend for a fresh token.

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": "conn_tenant_123_gsheets",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "successRedirectUri": "https://your-app.com/connect/success",
    "errorRedirectUri": "https://your-app.com/connect/error"
  }'

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: 'conn_tenant_123_gsheets',
  workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  successRedirectUri: 'https://your-app.com/connect/success',
  errorRedirectUri: 'https://your-app.com/connect/error',
})

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="conn_tenant_123_gsheets",
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    success_redirect_uri="https://your-app.com/connect/success",
    error_redirect_uri="https://your-app.com/connect/error",
)

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: 'conn_tenant_123_gsheets',
    workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    successRedirectUri: 'https://your-app.com/connect/success',
    errorRedirectUri: 'https://your-app.com/connect/error',
  }),
})
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": "conn_tenant_123_gsheets",
        "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "successRedirectUri": "https://your-app.com/connect/success",
        "errorRedirectUri": "https://your-app.com/connect/error",
    },
)
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.

For OAuth2 integrations, Weavz selects the OAuth app when the connect token is created. Team, Scale, and Enterprise organizations can register tenant-owned OAuth apps for branded consent screens, custom scopes, and provider quota isolation. If an eligible tenant-owned app exists for the integration, new connections use it by default; otherwise, Weavz uses the platform-managed OAuth app where one is configured.

Errors

Status	Code	Description
`400`	`NO_OAUTH_APP`	No OAuth app is configured for this integration
`403`	`CUSTOM_OAUTH_APP_PLAN_REQUIRED`	Tenant-owned OAuth apps are not available on the current plan
`409`	`TENANT_OAUTH_APP_REQUIRED`	A tenant-owned OAuth app exists and must be used for new connections
`404`	`INTEGRATION_NOT_FOUND`	Integration not found
`404`	`OAUTH_APP_NOT_FOUND`	Requested OAuth app does not exist or is not available to the organization

Get Connect Session

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

Retrieve a connect session by its Weavz session ID using your API key. Use this when your backend stored the session ID and wants an authenticated status lookup.

Path Parameters

Field	Type	Description
`sessionId`	string	Connect session ID

Response

json

{
  "session": {
    "id": "c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111",
    "integrationName": "google-sheets",
    "connectionName": "Google Sheets",
    "externalId": "conn_tenant_123_gsheets",
    "status": "COMPLETED",
    "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
    "error": null,
    "expiresAt": "2025-01-15T14:30:00.000Z",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Example

bash

curl https://api.weavz.io/api/v1/connect/session/c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111 \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

const { session } = await client.connect.getSession('c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111')

python

result = client.connect.get_session("c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111")
session = result["session"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/connect/session/c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111', {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

res = httpx.get(
    "https://api.weavz.io/api/v1/connect/session/c1f0f3c8-46ed-4a42-b7a2-0c3db3e7a111",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Errors

Status	Code	Description
`403`	`FORBIDDEN`	Session belongs to another organization
`404`	`NOT_FOUND`	Connect session not found

Poll Connect Session

POST/api/v1/connect/session/poll

Retrieve the status and result of a connect session using the short-lived cst_ token returned by POST /api/v1/connect/token. Poll this endpoint after the user completes (or closes) the connect page.

Request Body

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

Response

json

{
  "status": "COMPLETED",
  "connectionId": "c1d2e3f4-5678-90ab-cdef-1234567890ab",
  "integrationName": "google-sheets",
  "externalId": "conn_tenant_123_gsheets",
  "error": null
}

Session statuses:

Status	Description
`PENDING`	Connect page not yet opened or user still authorizing
`CONNECTING`	Authorization is being completed
`COMPLETED`	Authorization succeeded, `connectionId` contains the new connection
`FAILED`	Authorization failed, `error` field contains the error message

Example

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)

python

result = client.connect.wait(token)

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 data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/connect/session/poll",
    json={"token": token},
)
data = res.json()

Errors

Status	Code	Description
`400`	`MISSING_TOKEN`	Token was not provided
`401`	`INVALID_TOKEN`	Token is invalid or expired